ZetBot

外观

VuePress 生成静态站点

约 1597 字大约 5 分钟

markdownvuepress

2025-11-30

安装 VuePress

根据官方文档，可以用 pnpm create vuepress blog 来创建一个新的 VuePress 项目，但是使用 Plume 主题提供的更加方便。

pnpm create vuepress-theme-plume@latest
┌  Welcome to VuePress and vuepress-theme-plume !
│
◇  Where would you want to initialize VuePress?
│  blog
│
◇  Site Name:
│  Blog
│
◇  Site Description:
│  undefined
│
◇  Do you want to use multiple languages?
│  No
│
◇  Select the default language of the site
│  简体中文
│
◇  Use TypeScript?
│  Yes
│
◇  Select a bundler
│  Vite
│
◇  Deploy type:
│  GitHub Pages
│
◇  Initialize a git repository?
│  Yes
│
◇  Install dependencies?
│  Yes
│
◐  🚀 CreatinguserInfo ...
◇  🎉 Create success!
│
└  🔨 Execute the following command to start:
      cd blog
      pnpm run docs:dev

安装完毕，我们先看看效果。

$ cd blog
$ pnpm run docs:dev

然后就可以打开浏览器在 http://localhost:8080/ 查看效果了。

发布静态站点

VuePress 可以生成静态站点，用于部署到静态站点服务，例如 GitHub Pages、Netlify 等。也可以部署到自己的服务器上。

$ pnpm run docs:build

生成的静态站点在 docs/.vuepress/dist 目录下。如果使用 nginx 部署，需要在配置中添加如下内容：

root <parent_dir>/docs/.vuepress/dist;
index index.html index.htm;

当然也可以将文件目录下的所有文件复制到合适目录下，然后在 nginx 配置中指向该目录。

配置文件

配置文件在 docs/.vuepress 目录下：

  • client.ts：VuePress 的客户端配置文件
  • collections.ts：VuePress 的集合配置文件
  • config.ts：VuePress 的全局配置文件
  • navbar.ts：Plume 主题定义的导航栏配置文件
  • plume.config.ts：Plume 主题的配置文件

集合

集合主要分为两种类型，适应不同的内容组织需求：

  • post 类型：适用于碎片化内容，文章间关联较弱，如博客、专栏等
  • doc 类型：适用于结构化文档，内容关联紧密，如使用手册、产品文档、知识库等

集合的配置在 collections.ts 文件中。譬如，blog 集合的配置如下：

const blog = defineCollection({
  // post 类型，这里用于实现 博客功能
  type: "post",
  // 文档集合所在目录，相对于 `docs`
  dir: "blog",
  // 文档标题，它将用于在页面的面包屑导航中显示
  title: "Blog",
  // 文章列表页的链接，如果 `linkPrefix` 未定义，它也将作为相关的文章的 permalink 的前缀
  link: "/blog/",
  //   linkPrefix: '/article/', // 相关文章的链接前缀
  //   postList: true, // 是否启用文章列表页
  //   tags: true, // 是否启用标签页
  //   archives: true, // 是否启用归档页
  //   categories: true, // 是否启用分类页
  //   postCover: 'right', // 文章封面位置
  //   pagination: 15, // 每页显示文章数量
});

假设，我们有一个文档集合 project，包含了关于项目的使用手册，相关性比较强。我们可以将它配置为 doc 类型的集合。其中，index.md 作为项目的入口，包含了项目的介绍和目录。假设项目入口为 /project/，那么会自动去寻找到 docs/project/index.md 或者 docs/project/index.md 文件。

docs

插件

Vuepress 插件配置在 config.ts 文件中。大多数插件的配置都可以在 theme 的 markdown 配置中启用。一些插件如 fileTree 和 codeTree 需要添加到 theme 配置中。

export default defineUserConfig({
  ...

  theme: plumeTheme({
    ...

    /**
     * markdown
     * @see https://theme-plume.vuejs.press/config/markdown/
     */
    markdown: {
      abbr: true, // 启用 abbr 语法  *[label]: content
      //   annotation: true,   // 启用 annotation 语法  [+label]: content
      pdf: true, // 启用 PDF 嵌入 @[pdf](/xxx.pdf)
      //   caniuse: true,      // 启用 caniuse 语法 @[caniuse](feature_name)
      //   plot: true,         // 启用隐秘文本语法 !!xxxx!!
      //   bilibili: true,     // 启用嵌入 bilibili 视频 语法 @[bilibili](bid)
      //   youtube: true,      // 启用嵌入 youtube 视频 语法 @[youtube](video_id)
      //   artPlayer: true,    // 启用嵌入 artPlayer 本地视频 语法 @[artPlayer](url)
      //   audioReader: true,  // 启用嵌入音频朗读功能 语法 @[audioReader](url)
      //   icon: { provider: 'iconify' },        // 启用内置图标语法  ::icon-name::
      table: true, // 启用表格增强容器语法 ::: table
      //   codepen: true,      // 启用嵌入 codepen 语法 @[codepen](user/slash)
      //   replit: true,       // 启用嵌入 replit 语法 @[replit](user/repl-name)
      //   codeSandbox: true,  // 启用嵌入 codeSandbox 语法 @[codeSandbox](id)
      //   jsfiddle: true,     // 启用嵌入 jsfiddle 语法 @[jsfiddle](user/id)
      //   npmTo: true,        // 启用 npm-to 容器  ::: npm-to
      //   demo: true,         // 启用 demo 容器  ::: demo
      //   repl: {             // 启用 代码演示容器
      //     go: true,         // ::: go-repl
      //     rust: true,       // ::: rust-repl
      //     kotlin: true,     // ::: kotlin-repl
      //     python: true,     // ::: python-repl
      //   },
      math: {
        // 启用数学公式
        type: "katex",
      },
      //   chartjs: true,      // 启用 chart.js
      //   echarts: true,      // 启用 ECharts
      mermaid: true, // 启用 mermaid
      //   flowchart: true,    // 启用 flowchart
      //   image: {
      //     figure: true,     // 启用 figure
      //     lazyload: true,   // 启用图片懒加载
      //     mark: true,       // 启用图片标记
      //     size: true,       // 启用图片大小
      //   },
      include: {
        deep: true,
      }, // 在 Markdown 文件中导入其他 markdown 文件内容
      //   imageSize: 'local', // 启用 自动填充 图片宽高属性，避免页面抖动
      fileTree: true, // 启用文件树容器  ::: file-tree
      codeTree: true, // 启用代码树容器  ::: code-tree
    },

    ...
  }),
});

侧边栏

Vuepress 提供了两种方式配置侧边栏，包括：

  • 通过主题配置的 sidebar 选项配置侧边栏
  • 在类型为 doc 的集合中配置侧边栏

我们主要使用在类型为 doc 的集合中配置侧边栏。侧边栏配置在 collection.ts 文件中的每个 Collection.sidebar 中。假设我们有下面的目录结构。其中的 README.md 文件作为集合的入口，包含了集合的介绍和目录，也就是第一项 ["", ...]，其他文件依次对应侧边栏每一项。

docs

const latexDoc = defineCollection({
  // doc 类型，该类型带有侧边栏
  type: "doc",
  // 文档集合所在目录，相对于 `docs`
  dir: "notes/latex",
  // `dir` 所指向的目录中的所有 markdown 文件，其 permalink 需要以 `linkPrefix` 配置作为前缀
  // 如果 前缀不一致，则无法生成侧边栏。
  // 所以请确保  markdown 文件的 permalink 都以 `linkPrefix` 开头
  linkPrefix: "/notes/latex",
  // 文档标题，它将用于在页面的面包屑导航中显示
  title: "LaTeX 笔记",
  // 手动配置侧边栏结构
  sidebar: ["", "intro.md", "get-started.md", "equations.md"],
  // 根据文件结构自动生成侧边栏
  //   sidebar: "auto",
});

导航栏

导航栏配置在 navbar.ts 文件中。简单来说，它就是一个数组，每个元素都是一个对象，包含了导航栏的文本和链接。也可以通过 items 进行嵌套定义。

export default defineNavbarConfig([
  { text: "首页", link: "/" },
  { text: "博客", link: "/blog/" },
  { text: "标签", link: "/blog/tags/" },
  { text: "归档", link: "/blog/archives/" },
  {
    text: "笔记",
    items: [{ text: "LaTeX", link: "/notes/latex/" }],
  },
]);