VitePress 手把手完全使用手册

站长

2022年11月17日 16:41 · 阅读数 171

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 看到如下界面即表示运行成功。

VitePress 手把手完全使用手册

项目配置

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

VitePress 手把手完全使用手册

`Page` `Doc` 布局

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

---
layout: doc
---

VitePress 手把手完全使用手册

---
layout: page
---

VitePress 手把手完全使用手册

如何创建文档

假设你现在点击页面上的 快速开始 不出意外直接 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：跳转链接。

对标如下页面：

VitePress 手把手完全使用手册

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

对标如下页面：

VitePress 手把手完全使用手册

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

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

VitePress 手把手完全使用手册

文章底部上下翻页、在 `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',
  }
})

VitePress 手把手完全使用手册

打包后输出目录的配置
```
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' }]],
})
```

VitePress 手把手完全使用手册

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

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

VitePress 手把手完全使用手册

国际化配置

增加 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 周。申请成功后就坐等邮件吧。

VitePress 手把手完全使用手册

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

VitePress 手把手完全使用手册

在 config.js 中增加配置信息

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

结尾彩蛋

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

转载自:https://juejin.cn/post/7164276166084263972

VitePress 手把手完全使用手册

初始化项目

项目配置

布局

首页配置、Home 布局

Page Doc 布局

如何创建文档

全局配置对象

Nav 导航栏

Sidebar 侧边栏导航

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

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

其他全局配置信息

国际化配置

主题配置

拓展主题

定制主题

Markdown 语法拓展

Markdown 中使用 Vue

Vue 组件展示插件

Github Page 发布

Algolia 搜索

结尾彩蛋

首页配置、`Home` 布局

`Page` `Doc` 布局

`Nav` 导航栏

`Sidebar` 侧边栏导航

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

`Markdown` 语法拓展

`Markdown` 中使用 `Vue`

`Vue` 组件展示插件

`Github Page` 发布

`Algolia` 搜索