视频地址:手把手教你使用vitepress搭建并部署一个自己的知识库（无需服务器）

配套文档vitepress搭建并部署网站

命令

启动命令

npm run docs:dev

生成静态文件命令

 npm run docs:build

生成的静态文件在 .vitepress\dist 目录下

创建项目

话不多说，接下来开始我们的搭建步骤。对于开源项目，肯定是直接看官网和一些最佳实践了。

vitepress官网地址：https://vitepress.dev/

模仿的最佳实践（B站一个UP主的）：https://docs.zhengxinonly.com/

安装vitepress

首先新建文件夹，打开cmd窗口

npm add -D vitepress

初始化Vitepress

npm vitepress init

这是我的配置，简单介绍一下

• 第一个是在当前根目录下创建vitepress项目
• 站点标题和描述。后续可以在配置中改
• 主题，建议选择第二个，个人觉得比较好看
• 是否使用ts，我们个人学习就没必要ts了，主要还是我懒
• 是否添加脚本到package.json，这个还是需要的，启动命令，打包命令这些都得用

初始化成功后，使用vscode或webstorm打开文件夹，会看到这样一个目录。接下来简单介绍一下每个文件的含义

• .vitepress: 最核心的目录，
• theme目录: 自定义主题配置，css样式等
• config.mjs: 最核心的文件，各种配置导航栏、侧边栏、标题什么的都是在这里
• node_modules: 安装的依赖
• api-examples.md和markdown-examples.md: 官方给的两个示例
• index.md: 主页相关
• package.json和pnpm-lock.yml: 包管理工具需要用的

启动项目

npm run docs:dev

打开，看到这个，说明初始化成功

自定义配置

美化主页

对于主页，我们自定义的内容有哪些？如下图，8个地方可以自定义。接下来就一一叙述这8个地方怎么自定义的。

忘记了还有个页脚：

**9 ** 这个是直接配置footer，在config.mjs文件中的defineConfig 中的themeConfig下面配置就可以了

2-6是在index.md文件中自定义的。简单介绍一下对应关系

name<==>2 text<==>3 tagline<==>4 actions<==>5 features<==>6

需要说明的是，对于 5 这两个按钮，是可以跳转的，link指定路径，比如/api-example就是在项目根目录下找api-example.md这个文件

修改后的页面如下：

1、7、8 这三个配置是在config.mjs中配置的

其中，，，。description是SEO要用的，我们不用关注。

最后的结果是这样。

主页扩展

我们可能还想要对页面进行进一步美化，添加一些图标。可以去这个网站找图片https://www.iconfont.cn/

将找到的图片放在根目录下的 目录下。

最后美化的效果如图：

TODO：

• logo的配置是在config.mjs添加。（注意是themeConfig不是config）

logo: "logo.svg",   // 配置logo位置，public目录

• vitepress原生支持国外的sociallink，如果是国内需要自行复制svg代码。如图：

• 添加搜索栏，config.mjs中的themeConfig（支持国际化需要进一步配置 ）

美化文章页

默认进来官方给的示例是三边栏的

左边是sidebar的配置，右边是显示的文章目录（默认显示一二级）。

下面叙述这个是怎么配置的。sidebar可以是数组，也可以是对象。还是修改 config.mjs

最后的结果是这样

右侧导航栏默认索引的是md文件的一二级标题，可能需要定义索引的标题级别和On this page这个说明。这个时候需要在config.mjs中配置下面这两个选项，outlineTitle用于替代On this page。outline定义展示的标题级别，这里定义2-6级

最后美化后的文章目录是这样

自动生成侧边栏

我们使用这种配置时常常是一个目录有很多md文件，这些md文件所在的目录对应导航栏的一个选项。侧边栏的配置需要自己手写一个个路由映射到相应的文件上，那么有没有一个自动生成侧边栏的工具呢？根据一个目录下面的所有md文件自动生成路由，可以使用下面这个脚本

在 .vitepress 目录下创建 utils 文件夹 再创建一个auto-sidebar.js文件

import path from "node:path";
import fs from "node:fs";

// 文件根目录
const DIR_PATH = path.resolve();
// 白名单,过滤不是文章的文件和文件夹
const WHITE_LIST = [
  "index.md",
  ".vitepress",
  "node_modules",
  ".idea",
  "assets",
];

// 判断是否是文件夹
const isDirectory = (path) => fs.lstatSync(path).isDirectory();

// 取差值
const intersections = (arr1, arr2) =>
  Array.from(new Set(arr1.filter((item) => !new Set(arr2).has(item))));

// 把方法导出直接使用
function getList(params, path1, pathname) {
  // 存放结果
  const res = [];
  // 开始遍历params
  for (let file in params) {
    // 拼接目录
    const dir = path.join(path1, params[file]);
    // 判断是否是文件夹
    const isDir = isDirectory(dir);
    if (isDir) {
      // 如果是文件夹,读取之后作为下一次递归参数
      const files = fs.readdirSync(dir);
      res.push({
        text: params[file],
        collapsible: true,
        items: getList(files, dir, `${pathname}/${params[file]}`),
      });
    } else {
      // 获取名字
      const name = path.basename(params[file]);
      // 排除非 md 文件
      const suffix = path.extname(params[file]);
      if (suffix !== ".md") {
        continue;
      }
      res.push({
        text: name,
        link: `${pathname}/${name}`,
      });
    }
  }
  // 对name做一下处理，把后缀删除
  res.map((item) => {
    item.text = item.text.replace(/\.md$/, "");
  });
  return res;
}

export const set_sidebar = (pathname) => {
  // 获取pathname的路径
  const dirPath = path.join(DIR_PATH, pathname);
  // 读取pathname下的所有文件或者文件夹
  const files = fs.readdirSync(dirPath);
  // 过滤掉
  const items = intersections(files, WHITE_LIST);
  // getList 函数后面会讲到
  return getList(items, dirPath, pathname);
};

使用时，需要导入函数名，

在**.vitepress**目录下的config.mts文件中 最上面导入

import { set_sidebar } from "./utils/auto-sidebar.js";	// 改成自己的路径

直接使用。第一个/front-end/react常常是nav的link，这个set_sidebar传递的参数是相对于根路径的文件夹路径，返回的是每个文件夹中文件的名称和链接

sidebar: { "/front-end/react": set_sidebar("front-end/react") },

美化地址栏icon

我们可能还需要修改浏览器地址栏的左边图标

在config.mjs 文件中defineConfig下面直接配置即可

head: [["link", { rel: "icon", href: "/logo.svg" }]],

❗如果需要配置路径base，这个href也需要添加base路径作为前缀

设置搜索框

在config.mjs 文件中的defineConfig下的 themeConfig下面直接配置即可

   // 设置搜索框的样式
    search: {
      provider: "local",
      options: {
        translations: {
          button: {
            buttonText: "搜索文档",
            buttonAriaLabel: "搜索文档",
          },
          modal: {
            noResultsText: "无法找到相关结果",
            resetButtonTitle: "清除查询条件",
            footer: {
              selectText: "选择",
              navigateText: "切换",
            },
          },
        },
      },
    },

修改字体样式

在.vitepress目录下的theme目录中的 style.css 文件中的最下方添加

字体放在 public 下的font文件夹下 需要自己创建文件夹

/*导入字体*/
@font-face {
  font-family: 'customFont';
  src: url('/font/harmony.ttf') format('truetype');
}
:root {
  --vp-font-family-base: "customFont";
  --vp-font-size-base: 17px;
}
/*修改文章代码块的 字体 和 大小*/
body{
  font-size: var(--vp-font-size-base);
  font-family: var(--vp-font-family-base);
}
.vp-doc [class*='language-'] code{
  font-size: var(--vp-font-size-base);
  font-family: var(--vp-font-family-base);
}
.vp-doc :not(pre, h1, h2, h3, h4, h5, h6) > code{
  font-size: var(--vp-font-size-base);
  font-family: var(--vp-font-family-base);
  color: var(--vp-c-sponsor);
}
/*修改超链接颜色、取消下方横线*/
.vp-doc a {
  font-size: var(--vp-font-size-base);
  color: var(--vp-c-red-2);
  text-decoration:none;
}
/*修改加粗字体颜色*/
.vp-doc strong{
  color: var(--vp-c-sponsor);
}