TDL的个人笔记

切换主题

5分钟搞定VitePress自动侧边栏配置，告别手动维护 ​

说实话，刚用 VitePress 搭博客那会儿，最让我头疼的就是侧边栏。

每写一篇新文章，就得手动去 config.mts 里加一条配置。文章少的时候还好，文章一多，真的搞不动。

你知道吗？其实 VitePress 可以自动生成侧边栏和文章列表！

今天就把这个让我省了大把时间的方案分享给你。

🎯 痛点：手动维护侧边栏有多烦 ​

先说说我的情况。

我用 VitePress 搭建了一个个人博客，文章都放在 docs/已发布/ 目录下。一开始文章少，配置文件是这样的：

typescript
sidebar: [
  {
    text: "文章",
    items: [
      { text: "文章1", link: "/已发布/文章1" },
      { text: "文章2", link: "/已发布/文章2" },
    ],
  },
];

看着挺简单对吧？

但当我写了10篇、20篇文章后，每次发布新文章都要改配置。而且文章是按发布时间排序的，新文章要插在最前面，得手动调整顺序。

说白了，这事儿重复又机械，完全不应该人工来做。

说句大实话：程序员的时间，不该浪费在这种体力活上。

🔍 探索：有没有自动化的方案 ​

VitePress 官方提供了两个关键能力：

  1. createContentLoader — 构建时数据加载，扫描目录提取 frontmatter
  2. 第三方插件 vitepress-sidebar — 一行代码生成侧边栏配置

两个配合使用，就能实现侧边栏自动生成 + 文章列表页自动渲染。

关键发现：不是 VitePress 不支持自动化，而是需要把官方能力和插件组合起来用。

💡 实战：两步搞定 ​

第一步：安装插件 + 配置侧边栏 ​

bash
pnpm add -D vitepress-sidebar

打开 .vitepress/config.mts，用 generateSidebar 自动生成：

typescript
import { defineConfig } from "vitepress";
import { generateSidebar } from "vitepress-sidebar";

export default defineConfig({
  title: "TDL的个人笔记",
  description: "年纪大了，记性不好，写点东西记录一下",
  lang: "zh-CN",
  themeConfig: {
    nav: [
      { text: "首页", link: "/" },
      { text: "文章列表", link: "/已发布" },
    ],

    // 自动生成侧边栏
    sidebar: generateSidebar({
      documentRootPath: "/docs",
      useTitleFromFileHeading: true,
      useFolderTitleFromIndexFile: true,
      useFolderLinkFromIndexFile: true,
      sortMenusByFrontmatterOrder: true,
      sortFolderTo: "top",
      collapsed: false,
    }),

    search: { provider: "local" },
  },
});

第二步：用 createContentLoader 做文章列表页 ​

创建 docs/已发布/articles.data.ts：

typescript
import { createContentLoader } from "vitepress";

export default createContentLoader("已发布/*.md", {
  includeSrc: true,
  transform(rawData) {
    return rawData
      .filter((item) => item.frontmatter.date)
      .map(({ url, frontmatter }) => ({
        url,
        title: frontmatter.title || url,
        date: frontmatter.date,
        description: frontmatter.description || "",
      }))
      .sort((a, b) => (b.date > a.date ? 1 : b.date < a.date ? -1 : 0));
  },
});

创建 docs/已发布/index.md，用 Vue 组件渲染列表：

markdown
---
title: 文章列表
---

<script setup>
import { data as articles } from './articles.data.ts'
</script>

<div class="article-list">
  <a v-for="article in articles" :href="article.url" class="article-card">
    <span class="article-date">{{ article.date }}</span>
    <span class="article-title">{{ article.title }}</span>
  </a>
</div>

搞定！

真的绝了：侧边栏和文章列表全部自动生成。

📋 给文章加 frontmatter ​

每篇文章开头加这样的配置就行：

yaml
---
title: 文章标题
description: 文章的简短描述
date: 2025-03-26
order: 1
---
字段作用
title侧边栏显示的标题
description文章列表页显示的摘要
date列表页按日期倒序排列
order侧边栏按 order 排序（配合 sortMenusByFrontmatterOrder）

✍️ 总结 ​

现在的写作流程变成了：

  1. 写文章，加 frontmatter
  2. 保存到 已发布 目录
  3. 完事儿

侧边栏自动更新，文章列表自动排序，全部零手动维护。

工具的价值，在于让人专注于创造，而不是维护。

如果你也在用 VitePress 写博客，强烈推荐试试这个方案。一次配置，长期省心，太香了！

你平时用什么工具写博客？有没有遇到过类似的"体力活"问题？欢迎在评论区聊聊。