这是一份为你整合好的完整版 VitePress 现代化博客/文档系统搭建教程（已内置侧边栏自动生成插件）。你可以直接按步骤复制命令和代码进行配置。

🛠️ 第一部分：环境准备

在开始之前，请确保你的电脑上已经安装了 Node.js 20 或更高版本。

🚀 第二部分：极速搭建步骤

1. 创建项目并安装依赖

打开你的终端（Terminal），依次复制并运行以下命令：

Bash

# 1. 创建并进入项目文件夹（文件夹名可自定义）
mkdir my-vitepress-note && cd my-vitepress-note

# 2. 初始化 package.json
npm init -y

# 3. 安装 VitePress 核心依赖
npm add -D vitepress

# 4. 安装自动化侧边栏插件
npm add -D vitepress-plugin-auto-sidebar

2. 运行官方初始化向导

在终端中运行以下命令来启动 VitePress 的官方配置向导：

Bash

npx vitepress init

向导选项推荐选择（一路敲回车即可）：

• Where should VitePress initialize the config? ➔ 直接回车（默认 ./）
• Where should VitePress look for your markdown files? ➔ 直接回车（默认 ./）
• Site title: ➔ 输入你的网站标题（如：我的技术笔记）
• Site description: ➔ 输入一句描述（如：好记性不如烂笔头）
• Theme: ➔ 选 Default Theme（默认主题）
• Use TypeScript...? ➔ 选 Yes
• Add VitePress npm scripts...? ➔ 选 Yes

📝 第三部分：核心配置文件（直接复制）

初始化完成后，打开项目中的 .vitepress/config.mts 文件，清空里面的全部内容，然后将以下代码完整地复制粘贴进去：

TypeScript

import { defineConfig } from 'vitepress'
import { getSidebar } from 'vitepress-plugin-auto-sidebar'

export default defineConfig({
  // 1. 网站基础配置
  title: "我的技术笔记", 
  description: "基于 VitePress 构建的现代化高颜值笔记系统",
  cleanUrls: true, // 开启干净的 URL（不带 .html 结尾）

  // 2. 主题核心配置
  themeConfig: {
    // 顶部右上角导航栏
    nav: [
      { text: '首页', link: '/' },
    ],

    // 社交链接图标（可选）
    socialLinks: [
      { icon: 'github', link: 'https://github.com' }
    ],

    // 3. 自动化侧边栏：核心配置
    // 插件会自动扫描你的文件夹目录，根据 Markdown 的一级标题自动生成菜单
    sidebar: getSidebar({
      contentRoot: '/',       // 扫描的根目录
      contentDirs: null,      // 自动扫描根目录下的所有非系统文件夹
      collapsible: true,      // 菜单是否允许折叠
      collapsed: false,       // 初始状态下菜单默认展开
    }),

    // 页脚配置
    footer: {
      message: 'Released under the MIT License.',
      copyright: `Copyright © ${new Date().getFullYear()} Present`
    },

    // 搜索功能（内置本地全局搜索）
    search: {
      provider: 'local'
    }
  }
})

📂 第四部分：推荐的文件目录结构

为了让侧边栏看起来井井有条，建议在项目根目录下按分类创建文件夹。插件会自动将文件夹识别为“菜单大类”，将里面的 .md 文件识别为“子文章”。

推荐结构如下：

Plaintext

my-vitepress-note/
├── .vitepress/              # 系统配置目录
│   └── config.mts           # 你刚刚粘贴代码的文件
├── 01.前端技术/              # 分类文件夹 1
│   ├── 01.Vue3核心指南.md    # 文章（01. 前缀用于控制侧边栏排序）
│   └── 02.Vite性能优化.md
├── 02.后端开发/              # 分类文件夹 2
│   └── 01.Docker部署架构.md
├── index.md                 # 网站主页（向导自动生成的）
└── package.json             # 项目配置文件

✍️ 第五部分：日常写作与发布工作流

配置完成后，你的日常写作流程将变得极其爽快：

1. 创建文章：在对应的分类文件夹下，直接新建一个 xxxx.md 文件。

2. 编写标题：在 Markdown 文件的最顶部写上一个 # 一级标题。

   注意：自动侧边栏插件会自动抓取这个 # 一级标题 作为网页左侧菜单的名字，你的文件名叫什么都不影响菜单显示。

3. 如何控制排序：

   • 如果想让某个文件夹排在前面，文件夹命名可以加上数字前缀，如 01.前端技术。
   • 如果想让某篇文章排在前面，文件命名可以加上数字前缀，如 01.Vue3核心指南.md。
   • 插件在渲染侧边栏时，会自动把这些 01.、02. 的数字前缀隐去，界面依然保持纯文字的整洁。

🏃 第六部分：运行指令

在项目的终端里，你可以使用以下三个最常用的指令：

Bash

# 1. 启动本地预览（日常写作、修改配置时用）
npm run docs:dev

# 2. 编译打包（当你写完所有文章，准备发布到线上时运行）
npm run docs:build

# 3. 本地预览打包后的效果
npm run docs:preview