VitePress 手把手完全使用手册Vite & Vue支持的静态站点生成器。简单、强大、高效。满足您一直想要的现代S

VitePress 是基于 Vite 的静态网站生成器（文档工具）。

初始化项目

创建文件夹并进入到项目的目录中。当然如果你喜欢可以完全手动操作。

# mkdir 创建文件夹指令； && 表示当前命令执行成功后会执行下一条指令。
mkdir vitepress-starter && cd vitepress-starter

初始化项目，官网默认使用了 yarn 作为依赖管理工具。
```
yarn init
```
安装项目所需的依赖 vitepress 和 vue
```
yarn add --dev vitepress vue
```

创建第一个示例文件。如果你愿意可以手动操作

# echo 写入内容到项目的 docs/index.md 中
mkdir docs && echo '# Hello VitePress' > docs/index.md

在 package.json 中增加打包以及运行的指令。

"scripts": {
  "docs:dev": "vitepress dev docs", // 本地运行调试
  "docs:build": "vitepress build docs", // 项目打包：最终结果会在 .vitepress/dist 中
  "docs:serve": "vitepress serve docs" // 预览打包后的效果，此命令只有 build 成功后才会执行成功。
},

执行 npm run docs:dev 看到如下界面即表示运行成功。

项目配置

目标 1:1 复现 vitepress 的布局。

布局

VitePress 的布局整体可以分为 4 种，分别为：doc page home 和没有任何默认布局（空白页面）


需要注意的是，下面的语法一定要写在 md 文档的头部才会生效
---
layout: doc | page | home
---


// 通过此语法可以将整个页面变成空白页面，适合自定义的布局
{{ $formatter.layout }}

首页配置、`Home` 布局

点击查看首页配置，并结合下图参考对应配置

---
layout: home

hero:
  name: 主标题
  text: 内容信息
  tagline: 副内容信息
  image:
    src: /logo.png
    alt: 网站的 logo 图片
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/what-is-vitepress
    - theme: alt
      text: 在 github 上查看
      link: https://github.com/vuejs/vitepress
features:
  - icon: ⚡️
    title: 这里是功能区 1
    details: 这里是功能区 1 详情信息
  - icon: 🖖
    title: 这里是功能区 2
    details: 这里是功能区 2 详情信息
  - icon: 🛠️
    title: 这里是功能区 3
    details: 这里是功能区 3 详情信息
---

`Page` `Doc` 布局

这两种基本都是在书写文档的详细内容时而需要的布局。从表现形式上看也只是文章内容显示位置上面的不同及 page 相比较 doc 会默认缺少一些内容比如 Edit Link，NextPage PrePage 等。大多数情况下在编写内容时推荐使用 doc。

---
layout: doc
---

---
layout: page
---

如何创建文档

假设你现在点击页面上的 快速开始 不出意外直接 404 了，此时查看首页配置 快速开始的 link 为 /guide/what-is-vitepress

解决此问题：在 /docs 下新建文件 guide/what-is-vitepress.md 随便写入内容。再次点击即可访问。

VitePress 会根据 docs/ 下的文件内容映射成可访问路由。比如 /docs/guide/getting-started.md 则访问地址为 http://localhost:5173/guide/getting-started

文档书写规范推荐为以下结构


├─ docs
│  ├─ guide
│  │  ├─ getting-started.md
│  │  └─ what-is-vitepress.md
│  ├─ theme
│  │  ├─ theme-nav.md
│  │  └─ theme-sidebar.md
│  └─ index.md
└─ package.json

全局配置对象

VitePress 提供了一个配置对象，该对象应当存在于 /docs/.vitepress/config.js 中。在这里可以配置 Nav Sidebar 等重要信息。

在 .vitepress 中新建 config.js 文件并增加如下代码。


import { defineConfig } from 'vitepress';

export default defineConfig({});

`Nav` 导航栏

Nav 配置有两种方式，直接点击跳转和下拉菜单样式。详情参考以下配置信息。主要有以下字段：

link：当触发点击事件时跳转的地址；可以是外链也可以是项目内的路径。
activeMatch：需要被高亮的 nav 。

text：显示到页面的信息。

import { defineConfig } from 'vitepress';

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide', activeMatch: '/guide/what-is-vitepress' },
      {
        text: '下拉选择框',
        items: [
          { text: 'options-1', link: '/' },
          { text: 'options-2', link: 'http://www.baidu.com' }
        ]
      }
    ]
  }
});

社交链接 严格来说不算 nav 范畴，但是显示位置基本相同。

export default defineConfig({
  themeConfig: {
    socialLinks: [{ icon: "github", link: "https://github.com" }],
  }
});

icon：discord facebook github instagram linkedin slack twitter youtube 或者 svg 字符串
link：跳转链接。

对标如下页面：

`Sidebar` 侧边栏导航

sidebar 同样有两种配置方式。接受以下配置对象：

text：侧边栏块的 title。
items：侧边栏的每一项，text 为标题；link 为跳转地址。
collapsible：菜单是否为可折叠的 Boolean。
collapsed：是否默认折叠 Boolean 只有配置 collapsiable 时此配置才会生效。

数组配置方式

sidebar: [
  {
    text: 'Guide',
    items: [
      { text: 'Introduction', link: '/guide/what-is-vitepress' },
      { text: 'Getting Started', link: '/getting-started' },
    ],
    collapsible: true,
    collapsed: true
  }
],

对象配置方式

sidebar: {
  '/guide/': [
    {
      text: 'Guide',
      items: [
        { text: 'Index', link: '/guide/' }, // /guide/index.md
        { text: 'One', link: '/guide/one' }, // /guide/one.md
        { text: 'Two', link: '/guide/two' } // /guide/two.md
      ]
    }
  ]
}

 1) 适合文档没有那么多的时候；
 2) 能够更好的组织文档结构。

对标如下页面：

静态资源与导航路由的路径书写规则。

静态资源：推荐放入 /docs/public 文件夹中。随后在 md 中使用时以 ![image](/images/xxx.png)。 / 以 public 开始。

路径配置规则：以 /docs 为根目录，进行配置；/ 以 docs 开始。示例：

export default defineConfig({
  themeConfig: {
    // link 点击时跳转的默认地址
    // activeMatch 无论在 guide 下的哪一个子菜单都会保持高亮。
    nav: [{ text: '指导', link: '/guide/what-is-vitepress', activeMatch: '/guide' }],
    sidebar: {
      '/guide/': [
        {
          text: '介绍',
          items: [
            { text: '什么是 VitePress', link: '/guide/what-is-vitepress' },
            { text: '快速开始', link: '/guide/getting-started' },
            { text: '配置', link: '/guide/configuration' },
            { text: '发布', link: '/guide/deploying' }
          ],
          collapsible: true
        }
      ]
    }
  }
});

文章底部上下翻页、在 `Github` 编辑此页、最后更新时间

上下翻页 此功能虽是默认提供，也可以通过配置来定制默认的文字。

export default {
  themeConfig: {
    docFooter: { prev: '上一篇', next: '下一篇' }
  }
}

在 Github 编辑此页 可以通过 editLink 来进行配置

pattern：可以分为两部分，:path 为变量内容指当前的文件名称。:path 之前的部分则是项目的 /docs 的 github 的文档地址。

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

最后更新时间 需要在 themeConfig 平级去开启此选项，然后在 themeConfig 中可以去定制其展示文字。需要注意的是配置之后不会立即生效。
```
export default {
  lastUpdated: true,
  themeConfig: {
    lastUpdatedText: "最近更新时间"
  }
}
```

其他全局配置信息

主 title 内容与图片配置。

export default defineConfig({
  title: '自定义的 title',
  themeConfig: {
    logo: '/test.jpg',
  }
})

打包后输出目录的配置
```
export default {
  outDir: '../dist'
}
```
markdown 主题配置点击查看文档
description 配置后会显示页面中 <meta name="description" content="xxxx"> 显示
```
export default defineConfig({
  description: '自定义的 description',
})
```
head 配置后会显示在页面中的 head 中。可以配置多个。应该也能扩展 VitePress 的功能，有兴趣的可以研究下。
```
export default defineConfig({
  head: [['meta', { name: 'keywords', content: 'HTML, CSS, JavaScript' }]],
})
```

页脚通过 footer 进行配置。如果 Sidebar 存在则页脚不会存在

export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2019-present Evan You'
    }
  }
}

国际化配置

增加 locales 配置，修改语言环境以及 title 和 description 的国际化内容；此时可以去除上面配置的与 locales 平级的 title 和 description。

export default defineConfig({
  locales: {
    "/": {
      lang: "zh-CN",
      title: "自定义的 title",
      description: "自定义的 description"
    },
    "/en/": {
      lang: "en-US",
      title: "Custom title",
      description: "Custom description"
    }
  },
});

在 themeConfig 下增加 localeLinks 切换国际化的下拉框；

export default defineConfig({
  themeConfig: {
    localeLinks: {
      items: [
        { text: "简体中文", link: "/" },
        { text: "English", link: "/en" }
      ]
    },
  }
});

将 themeConfig 下的内容进行拆分并在 /docs 下新增 /en 文件夹用于存放国际化文档。

export default defineConfig({
  themeConfig: {
    locales: {
      // 函数功能就是将需要语言转换的内容分开成两套配置，后续有示例
      "/": getChineseThemeConfig(),
      "/en/": getEnglishThemeConfig()
    },
  }
})

具体示例代码以及项目结构演示；

export default defineConfig({
  outDir: "../dist",
  head: [["meta", { name: "keywords", content: "HTML, CSS, JavaScript" }]],
  lastUpdated: true,
  locales: {
    "/": {
      lang: "zh-CN",
      title: "自定义的title",
      description: "自定义的description"
    },
    "/en/": {
      lang: "en-US",
      title: "Custom title",
      description: "Custom description"
    }
  },
  themeConfig: {
    logo: "/test.jpg",
    socialLinks: [{ icon: "github", link: "https://github.com" }],
    localeLinks: {
      text: "",
      items: [
        { text: "中文", link: "/" },
        { text: "English", link: "/en/" }
      ]
    },
    locales: {
      // 原本 themeConfig 下所有需要转换的信息通过手动写两套配置的方式全部处理一下
      // 例如 
      // 中文展示 docFooter: { prev: "上一页", next: "下一页" }
      // 英文展示 docFooter: { prev: "Pre page", next: "Next page" }
      "/": getChineseThemeConfig(),
      "/en/": getEnglishThemeConfig()
    }
  }
});

// 注意英文配置下路径也需要进行处理。
function getEnglishThemeConfig() {
  return {
    nav: [{ text: "Guide", link: "/en/guide/what-is-vitepress", activeMatch: "/en/guide/" }],
    sidebar: {
      "/en/guide/": [
        {
          text: "Description",
          items: [{ text: "What is VitePress", link: "/en/guide/what-is-vitepress" }],
          collapsible: true
        }
      ]
    },
    // ... ...
  };
}

国际化基本的目录结构应该如下这样；

. docs
├── en
│   ├── guide
│   │   └── what-is-vitepress.md
│   └── index.md 英文状态下的 index 也需要进行转换
├── guide
│   └── what-is-vitepress.md
├── index.md
├── node_modules

主题配置

主题的配置可以分为两种。拓展主题 定制主题 使用方式大体相同。

.vitepress 下新增 theme 文件夹以及 /theme/index.js 文件

无论使用哪种方式，哪怕不定制主题，也可以单独的修改它默认的样式。查看样式定制

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
}

拓展主题

使用 vitepress 提供的一些插槽拓展它的主题；查看布局插槽

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'

export default {
  ...DefaultTheme,
  // override the Layout with a wrapper component that
  // injects the slots
  Layout: MyLayout
}

<!--.vitepress/theme/MyLayout.vue-->
<script setup>
import DefaultTheme from 'vitepress/theme'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #aside-outline-before>
      My custom sidebar top content
    </template>
  </Layout>
</template>

定制主题

目前 Element-Plus 就是采用这种方式来开发的文档站点。 Element-Plus文档源码入口文件

// .vitepress/theme/index.js
import Layout from './Layout.vue'

export default {
  // 布局文件入口，
  Layout,

  // this is a Vue 3 functional component
  // 404 页面
  NotFound: () => 'custom 404',

  enhanceApp({ app, router, siteData }) {
    // 这里可以注册组件等内容在可以在文档中做 组件预览展示等功能。
  }
}

`Markdown` 语法拓展

语法拓展文档请移步这里。都是一些拓展语法比较简单。

`Markdown` 中使用 `Vue`

文档请移步这里。

`Vue` 组件展示插件

推荐几个插件，这里就不在演示 Demo。使用起来也是比较简单的；

vitepress-doc-plugin 相对推荐
vitepress-demo-editor 可交互的 demo 操作。根据需求推荐
vitepress-demo 比较推荐

`Github Page` 发布

根目录新建 deploy.sh 文件。并复制以下内容稍微修改。

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 删除文件需要根据实际打包的目录进行删除
rm -rf docs/.vitepress/dist/

# 生成静态文件
yarn docs:build

# 进入生成的文件夹
cd docs/.vitepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io 修改仓库地址
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master:gh-pages

cd -

创建 github 仓库。注意 Repository name 和本地的 base 配置相同

export default defineConfig({
  base: '/your-github-repository/'
})

package.json 中新增脚本并执行，虽然等个三两分钟直接访问 https://your-github.github.io/your-github-repository/。
```
"scripts": {
  "docs:deploy": "bash deploy.sh"
}
```

如果遇到异常参考 VuePress 搭建组件库文档 VuePress 部署

`Algolia` 搜索

本章节参考 VuePress 博客优化之开启 Algolia 全文搜索。

Algolia 开始之前务必通读文档

如果确认要引入该搜索时，需要保证你的项目可以用于外网访问。比如 githubpages

点击此链接进行 key，Algolia 申请，时间可能会比较漫长。官网说不超过 2 周。申请成功后就坐等邮件吧。

收到邮件后回复 I am the maintainer of the website, I can modify the code ~
再次收到邮件可能包含以下内容

在 config.js 中增加配置信息

algolia: {
  apiKey: "aea12a0a4281c855b5d23789e868f378",
  indexName: "interview-questions-record",
  // 如果 Algolia 没有为你提供 `appId` ，使用 `BH4D9OD16A` 或者移除该配置项
  appId: "XQYLP2L9WC"
}

结尾彩蛋

查看完整配置信息同时也和各位小伙伴分享一下，我前段时间总结的一些前端面试题。希望对正在找工作，即将找工作的一些小伙伴提供到帮助。2022面试题汇总如果内容有帮助到你，就点个 star 激励一下我吧。

VitePress 手把手完全使用手册

初始化项目

项目配置

布局

首页配置、Home 布局

Page Doc 布局

如何创建文档

全局配置对象

Nav 导航栏

Sidebar 侧边栏导航