vuepress使用笔记

本文章记录vuepress使用过程中的重点

注意：本笔记基于vuepress-theme-hope主题，使用Netlify托管网站，Vercel托管评论。

网站搭建

1. 初始化项目

npm init vuepress-theme-hope [dir]

2. 在github上新建仓库，并将项目推送到github上。
3. 关联Netlify与github仓库，完善相应配置。

常用配置

前提

所有配置基于以下结构为前提

import { hopeTheme } from "vuepress-theme-hope";

export default hopeTheme({
    // theme options
})

import { defineUserConfig } from "vuepress";
import theme from "./theme.js";

export default defineUserConfig({
    theme,
    // other user options
});

导航栏

导航栏菜单项可以直接使用文档路径定义，比如:

{
    navbar: [
        "home.md",
        "about.md"
    ]
}

但是，建议使用对象形式声明，其格式为：

interface NavbarMenuItem {
    text: string; // 链接名称
    link: string; // 链接
    icon?: string; // 图标
    activeMatch?: string; // 激活链接匹配，支持正则字符串
    children?: NavbarMenuItem[]; // 子菜单，渲染成下拉菜单
    prefix?: string; // 路径前缀，渲染时作为children中项目链接的前缀
}

注意

使用children后，link会失效，不需要再提供，不再有点击跳转功能。

下面看一个简单示例，更多详情请查看官方文档

展开示例

{
    navbar: [
        {
            text: "首页",
            link: "/"
        },
        {
            text: "随笔",
            link: "/essays/",
            prefix: "/essays/",
            children: [
                {
                    text: "主题一",
                    link: "/topic1/"
                },
                {
                    text: "主题二",
                    link: "/topic2/"
                }
            ]
        }
    ]
}

侧边栏

侧边栏菜单项格式与导航栏十分相似，不进行过多赘述。

使用sidebar选项对侧边栏进行手动配置

// theme options
{
    sidebar: {
        "/": [
            "",
            {
                text: "关于",
                link: "/about",
                children: [
                    "/aboutme.md",
                    "/aboutsite.md"
                ]
            }
        ]
    }
}

依据文件结构自动生成侧边栏

{
    sidebar: {
        "/notes/": "structure"
    }
}

提示

上面给出的配置方式都是基于路径的，如果所有路径共用侧边栏，不需要给出路径，只需要使用数组形式。点击查看详情

目录

自动生成目录

当每个文件夹文档中不存在README.md文档时，主题自动为每个文件夹文档生成目录页。对应路径为${文件夹url路径}/

自定义目录页

在对应文件夹中创建README.md文档，可以对目录页进行自定义。此时，可以在文档中使用<AutoCatalog />渲染目录列表

注意

主题使用vuepress-plugin-catalog渲染目录列表，依赖每个文档frontmatter的title属性，如果没有该属性，会导致目录标题缺失。

评论

当前只涉及waline，在使用评论功能，要先在配置文件中声明。

{
    plugins: {
        comment: {
            provider: "Waline",
            serverURL: "..."
        }
    }
}

然后，就是对LeanCloud和Vercel的配置，直接参照官方文档

注意

Vercel是一个静态站托管平台，现在用于托管Waline代码，是独立于当前站点的，所以代码库不能选择网站的仓库，而是应该新建一个仓库。

Markdown增强

主题对Markdown功能的增强均通过vuepress-plugin-md-enhance插件实现，只需要配置该插件选项即可开启各种增强功能。

{
    plugins: {
        mdEnhance: {
            // 各种功能增强选项
            tabs: true, // 选项卡支持
            codetabs: true, // 代码块分组支持
            container: true // 自定义容器支持
            // , ...
        }
    }
}

详情查看官方文档

复用主题组件

通过将主题中组件注册成全局组件的方式在markdown中复用。

import { registerComponentsPlugin } from "@vuepress/plugin-register-components";

export default defineUserConfig({
  // ...
  plugins: [
    // ...
    registerComponentsPlugin({
      components: {
        // 注册CategoryList为全局组件
        CategoryList: path.resolve(
          __dirname,
          "../../node_modules/vuepress-theme-hope/lib/client/modules/blog/components/CategoryList.js"
        ),
        // 注册TagList为全局组件
        TagList: path.resolve(
          __dirname,
          "../../node_modules/vuepress-theme-hope/lib/client/modules/blog/components/TagList.js"
        ),
      },
    }),
  ],
});

## 展示Category筛选列表
<CategoryList />

## 展示Tag筛选列表
<TagList />