VitePress 手把手完全使用手册

12,711 阅读10分钟

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

初始化项目

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

    # mkdir 创建文件夹指令; && 表示当前命令执行成功后会执行下一条指令。
    mkdir vitepress-starter && cd vitepress-starter
    
  2. 初始化项目,官网默认使用了 yarn 作为依赖管理工具。

    yarn init
    
  3. 安装项目所需的依赖 vitepressvue

    yarn add --dev vitepress vue
    
  4. 创建第一个示例文件。如果你愿意可以手动操作

    # echo 写入内容到项目的 docs/index.md 中
    mkdir docs && echo '# Hello VitePress' > docs/index.md
    
  5. package.json 中增加打包以及运行的指令。

    "scripts": {
      "docs:dev": "vitepress dev docs", // 本地运行调试
      "docs:build": "vitepress build docs", // 项目打包:最终结果会在 .vitepress/dist 中
      "docs:serve": "vitepress serve docs" // 预览打包后的效果,此命令只有 build 成功后才会执行成功。
    },
    
  6. 执行 npm run docs:dev 看到如下界面即表示运行成功。

vitepress01.jpg

项目配置

目标 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 详情信息
---

vitepress02.jpg

Page Doc 布局

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

---
layout: doc
---

vitepress05.jpg

---
layout: page
---

vitepress06.jpg

如何创建文档

假设你现在点击页面上的 快速开始 不出意外直接 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" }],
  }
});
  • icondiscord facebook github instagram linkedin slack twitter youtube 或者 svg 字符串

  • link:跳转链接。

对标如下页面:

vitepress03.jpg

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) 能够更好的组织文档结构。

对标如下页面:

vitepress04.jpg

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

静态资源:推荐放入 /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
        }
      ]
    }
  }
});

vitepress07.jpg

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

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

    export default {
      themeConfig: {
        docFooter: { prev: '上一篇', next: '下一篇' }
      }
    }
    
  2. Github 编辑此页 可以通过 editLink 来进行配置

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

    export default {
      themeConfig: {
        editLink: {
          pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
          text: 'Edit this page on GitHub'
        }
      }
    }
    
  3. 最后更新时间 需要在 themeConfig 平级去开启此选项,然后在 themeConfig 中可以去定制其展示文字。需要注意的是配置之后不会立即生效。

    export default {
      lastUpdated: true,
      themeConfig: {
        lastUpdatedText: "最近更新时间"
      }
    }
    

其他全局配置信息

  1. title 内容与图片配置。

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

vitepress08.jpg

  1. 打包后输出目录的配置

    export default {
      outDir: '../dist'
    }
    
  2. markdown 主题配置 点击查看文档

  3. description 配置后会显示页面中 <meta name="description" content="xxxx"> 显示

    export default defineConfig({
      description: '自定义的 description',
    })
    
  4. head 配置后会显示在页面中的 head 中。可以配置多个。应该也能扩展 VitePress 的功能,有兴趣的可以研究下。

    export default defineConfig({
      head: [['meta', { name: 'keywords', content: 'HTML, CSS, JavaScript' }]],
    })
    

vitepress09.jpg

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

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

vitepress10.jpg

国际化配置

  1. 增加 locales 配置,修改语言环境以及 titledescription 的国际化内容;此时可以去除上面配置的与 locales 平级的 titledescription

    export default defineConfig({
      locales: {
        "/": {
          lang: "zh-CN",
          title: "自定义的 title",
          description: "自定义的 description"
        },
        "/en/": {
          lang: "en-US",
          title: "Custom title",
          description: "Custom description"
        }
      },
    });
    
  2. themeConfig 下增加 localeLinks 切换国际化的下拉框;

    export default defineConfig({
      themeConfig: {
        localeLinks: {
          items: [
            { text: "简体中文", link: "/" },
            { text: "English", link: "/en" }
          ]
        },
      }
    });
    
  3. themeConfig 下的内容进行拆分并在 /docs 下新增 /en 文件夹用于存放国际化文档。

    export default defineConfig({
      themeConfig: {
        locales: {
          // 函数功能就是将需要语言转换的内容分开成两套配置,后续有示例
          "/": getChineseThemeConfig(),
          "/en/": getEnglishThemeConfig()
        },
      }
    })
    
  4. 具体示例代码以及项目结构演示;

    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。使用起来也是比较简单的;

  1. vitepress-doc-plugin 相对推荐

  2. vitepress-demo-editor 可交互的 demo 操作。根据需求推荐

  3. vitepress-demo 比较推荐

Github Page 发布

  1. 根目录新建 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 -
    
  2. 创建 github 仓库。注意 Repository name 和本地的 base 配置相同

    export default defineConfig({
      base: '/your-github-repository/'
    })
    
  3. package.json 中新增脚本并执行,虽然等个三两分钟直接访问 https://your-github.github.io/your-github-repository/

    "scripts": {
      "docs:deploy": "bash deploy.sh"
    }
    

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

Algolia 搜索

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

Algolia 开始之前务必通读 文档

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

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

vitepress11.jpg

  1. 收到邮件后回复 I am the maintainer of the website, I can modify the code ~

  2. 再次收到邮件可能包含以下内容

vitepress12.jpg

  1. config.js 中增加配置信息
algolia: {
  apiKey: "aea12a0a4281c855b5d23789e868f378",
  indexName: "interview-questions-record",
  // 如果 Algolia 没有为你提供 `appId` ,使用 `BH4D9OD16A` 或者移除该配置项
  appId: "XQYLP2L9WC"
}

结尾彩蛋

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