编写前端项目的说明/官方文档是前端基建必备技能之一。下面介绍在编写前端项目文档时会用到的工具，以及在常规布局中如何去使用。希望可以帮助开发同学快速获取相关知识点。

VitePress

VitePress 的作者是尤雨溪。

VitePress 是一个基于 Vue.js（Vue3）和 Vite 构建的静态网站生成器（SSG, Static Site Generator），它专为快速、轻量级且高性能的文档站点和其他静态网站设计。在可配置性上更加精简，没有复杂的插件系统，更适合于那些不需要大量自定义功能的小型到中型项目。

安装

在项目中安装依赖。

sh 复制代码

// npm
npm add -D vitepress

// pnpm
pnpm add -D vitepress

// yarn
yarn add -D vitepress

安装依赖后，通过初始化向导，可以帮助构建一个基本项目。

sh 复制代码

// npm
npx vitepress init

// pnpm
pnpm vitepress init

// yarn
pnpm vitepress init

成功构建项目后，目录结构如下：

lua 复制代码

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

配置和API

VitePress 提供的配置和API直观易懂，开发同学通过简易操作就能立竿见影地看到实际效果，实现所配即所得。因此，通过详细解析并实践官方文档中展示的各项配置选项与API用法，我们可以迅速掌握 VitePress 的核心配置及其API使用方法。

首页布局

如下图所示，首页可以划分为三块区域：导航栏、主页和页脚。

导航栏

功能	说明	配置 (.vitepress/config.js)
站点标题和图标	默认情况下，nav 显示 `config.title` 作为站点的标题。如果想更改导航栏上显示的内容，可以在 `themeConfig.siteTitle` 选项中定义自定义文本。	`config.title` / `themeConfig.siteTitle`
本地搜索	得益于 minisearch，VitePress 支持使用浏览器内索引进行模糊全文搜索。要启用此功能，只需在 `.vitepress/config.js` 文件中将 `themeConfig.search.provider` 选项设置为 `'local'` 即可	`search: { provider: 'local' }`
导航连接	可以定义 `themeConfig.nav` 选项以将链接添加到导航栏	`themeConfig.nav`
国际化	通过配置`config.locales`实现国际化	`config.locales`
主题切换	默认开启，通过配置`config.appearance`关闭主题切换	`config.appearance`
社交链接	通过`themeConfig.socialLinks`配置导航栏中展示带有图标的社交帐户链接	`themeConfig.socialLinks`

代码示例：站点标题和图标

默认情况下，nav 显示 config.title 作为站点的标题。如果想更改导航栏上显示的内容，可以在 themeConfig.siteTitle 选项中定义自定义文本。

如果站点有图标，则可以通过传递图片路径来显示它。应该将图标直接放在 public 中，并赋值该绝对路径。

js 复制代码

export default {
  title: "My Default Title",
  themeConfig: {
    siteTitle: 'My Custom Title',
    logo: '/my-logo.svg'
  }
}

添加图标时，它会与站点标题一起显示。如果只需要图标并且想要隐藏站点标题文本，请将 siteTitle 选项设置为 false。

js 复制代码

export default {
  themeConfig: {
    logo: '/my-logo.svg',
    siteTitle: false
  }
}

代码示例：本地搜索

本地搜索配置代码如下，

或者，你可以使用 Algolia DocSearch 或一些社区插件。

js 复制代码

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

代码示例：导航连接

可以定义 themeConfig.nav 选项以将链接添加到导航栏。

代码如下，其中 text 是 nav 中显示的实际文本，而 link 是单击文本时将导航到的链接。对于链接，将路径设置为不带 .md 后缀的实际文件，并且始终以 / 开头。

导航链接也可以是下拉菜单。为此，请替换 link 选项，设置 items 数组。

js 复制代码

export default {
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide' },
      { text: 'Config', link: '/config' },
      { text: 'Changelog', link: 'https://github.com/...' },
      { text: 'Dropdown Menu', items: [ { text: 'Item A', link: '/item-1' }, { text: 'Item B', link: '/item-2' }, { text: 'Item C', link: '/item-3' } ] }
    ]
  }
}

代码示例：国际化

要使用内置的 i18n (国际化) 功能，需要创建类似于下面的目录结构：

js 复制代码

docs/
├─ en/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ foo.md

然后在 docs/.vitepress/config.ts 中：

js 复制代码

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 共享属性和其他顶层内容...

  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    fr: {
      label: 'French',
      lang: 'fr', // 可选，将作为 `lang` 属性添加到 `html` 标签中
      link: '/fr/guide' // 默认 /fr/ -- 显示在导航栏翻译菜单上，可以是外部的

      // 其余 locale 特定属性...
    }
  }
})

代码示例：主题切换

默认值：true ，是否启用深色模式 (通过将 .dark 类添加到 <html> 元素)。

如果该选项设置为 true，则默认主题将由用户的首选配色方案决定。

如果该选项设置为 dark，则默认情况下主题将是深色的，除非用户手动切换它。

如果该选项设置为 false，用户将无法切换主题。

js 复制代码

export default {
  appearance: true // boolean | 'dark' | 'force-dark'
}

代码示例：社交链接

可以定义此选项以在导航栏中展示带有图标的社交帐户链接。

js 复制代码

export default {
  themeConfig: {
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: '...' },
      // 可以通过将 SVG 作为字符串传递来添加自定义图标：
      {
        icon: {
          svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
        },
        link: '...',
        // 也可以为无障碍添加一个自定义标签 (可选但推荐):
        ariaLabel: 'cool link'
      }
    ]
  }
}

主页

如下图所示，主页主要有两块内容：Hero 部分 、 Features 部分。除此之外还可以添加额外的 Markdown 内容。

Hero 部分

字段名称	说明
name	`text` 上方的字符，带有品牌颜色，预计简短，例如产品名称
text	hero 部分的主要文字，被定义为 `h1` 标签
tagline	`text` 下方的标语
image	`text` 和 `tagline` 区域旁的图片
actions	主页 hero 部分的操作按钮

yaml 复制代码

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  image:
    src: /logo.png
    alt: VitePress
  actions:
    - theme: brand
      text: Get Started
      link: /guide/what-is-vitepress
    - theme: alt
      text: View on GitHub
      link: https://github.com/vuejs/vitepress
---

Features 部分

字段名称	说明
icon	在每个 `feature` 框中显示图标
title	feature 的标题
details	feature 的详情
link	点击 feature 组件时的链接，可以是内部链接，也可以是外部链接
linkText	feature 组件内显示的链接文本，最好与 `link` 选项一起使用。例如 `Learn more`, `Visit page` 等
rel	`link` 选项的链接 rel 属性，例如 `external`
target	`link` 选项的链接 target 属性

yaml 复制代码

---
layout: home

features:
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...
  - icon:
      src: /cool-feature-icon.svg
    title: Another cool feature
    details: Lorem ipsum...
  - icon:
      dark: /dark-feature-icon.svg
      light: /light-feature-icon.svg
    title: Another cool feature
    details: Lorem ipsum...
---

Markdown 部分，效果如下图：

md 复制代码

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
---

// 额外的 Markdown 内容
## Getting Started 

You can get started using VitePress right away using `npx`!

npm init
npx vitepress init

页脚

配置好 themeConfig.footer，VitePress 将在全局页面底部显示页脚。

字段名称	说明	配置
message	版权前显示的信息	`themeConfig.footer.message`
copyright	实际的版权文本	`themeConfig.footer.copyright`

js 复制代码

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

可以使用 frontmatter 上的 footer 选项在单独页面上禁用此功能

yaml 复制代码

// frontmatter 配置
---
footer: false
---

内页布局

如下图所示，内页默认的常规布局包括：侧边栏、Markdown正文内容、大纲和Carbon Ads。

功能	字段名称	说明	展现形式
侧边栏	sidebar	在 `themeConfig.sidebar` 中配置侧边栏菜单。	基本用法 / 多侧边栏 / 可折叠的侧边栏组
Markdown内容	-	展示对应的`.md`文件内容	-
最后更新于	lastUpdated	要启用它，请将 `lastUpdated` 选项添加到配置中。	最近一条内容的更新时间会显示在页面右下角。
编辑链接	editLink	若要开启编辑链接功能，可以在配置文件中插入`themeConfig.editLink`选项。	编辑链接让你可以显示一个链接，以在 GitHub 或 GitLab 等 Git 管理服务上编辑页面。
上下页链接	prev / next	可以自定义上一页和下一页的文本和链接。	显示在文档页脚处。
大纲	outline	列出了页面内的各个标题及其对应的链接锚点，允许用户快速浏览和跳转到页面内的不同部分	显示在文档右侧。
Carbon Ads	carbonAds	可以通过`themeConfig.carbonAds`配置	VitePress 将在页面上显示广告。

侧边栏

侧边栏作为文档的关键导航组成部分，其菜单可以通过在 themeConfig.sidebar 对象内进行配置来定制化。

代码示例：基本用法

侧边栏菜单最基本的结构表现为一个链接数组。在这一层级上，我们首先定义侧边栏的不同"部分"，这些"部分"以其各自的text标题作为一级项目呈现，并且每个部分还包含了用于实际导航的项目列表，即items，它们充当子链接。

每个 link 都应指定以 / 开头的实际文件的路径。如果在链接末尾添加斜杠，它将显示相应目录的 index.md。

可以进一步将侧边栏项目嵌入到 6 级深度，从根级别上计数。请注意，深度超过 6 级将被忽略，并且不会在侧边栏上显示。

js 复制代码

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' },
          ...
        ]
      },
      {
        text: 'Guide',
        items: [
          // 显示的是 `/guide/index.md` 页面
          { text: 'Introduction', link: '/guide/' }
        ]
      }
    ]
  }
}

代码示例：多侧边栏

可能会根据页面路径显示不同的侧边栏。例如，如本站点所示，可能希望在文档中创建单独的侧边栏，例如"指南"页面和"配置参考"页面。

为此，首先将你的页面组织到每个所需部分的目录中.

md 复制代码

.
├─ guide/
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ config/
   ├─ index.md
   ├─ three.md
   └─ four.md

js 复制代码

export default {
  themeConfig: {
    sidebar: {
      // 当用户位于 `guide` 目录时，会显示此侧边栏
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Index', link: '/guide/' },
            { text: 'One', link: '/guide/one' },
            { text: 'Two', link: '/guide/two' }
          ]
        }
      ],

      // 当用户位于 `config` 目录时，会显示此侧边栏
      '/config/': [
        {
          text: 'Config',
          items: [
            { text: 'Index', link: '/config/' },
            { text: 'Three', link: '/config/three' },
            { text: 'Four', link: '/config/four' }
          ]
        }
      ]
    }
  }
}

代码示例：可折叠的侧边栏组

在侧边栏组的配置中引入 collapsed 选项后，系统会在界面中展示一个切换按钮，用户可通过点击该按钮来灵活地隐藏或显示各个侧边栏部分。

默认情况下，所有侧边栏部分在初始页面加载时都会处于 打开 状态。如果你想让它们初始时为 关闭 状态，请将 collapsed 选项设置为 true。

js 复制代码

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        collapsed: false, // true or false
        items: [...]
      }
    ]
  }
}

最后更新于

若要在页面右下角显示内容的最近更新时间，需在配置文件中包含 lastUpdated 选项以启用此功能。

必须提交 markdown 文件才能看到最后更新时间。

yaml 复制代码

// 全局配置
export default {
  lastUpdated: true
}

// frontmatter 配置
---
lastUpdated: false
---

编辑链接

编辑链接让你可以显示一个链接，以在 GitHub 或 GitLab 等 Git 管理服务上编辑页面。要启用它，可以将 themeConfig.editLink 选项添加到配置中。

yaml 复制代码

// 全局配置
export default {
  themeConfig: {
    editLink: {
    
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
    }
  }
}

// frontmatter 配置
---
editLink: false
---

上下页链接

在 markdown 文件中自定义上一页和下一页的文本和链接。

yaml 复制代码

// 仅自定义文本
---
prev: 'Get Started | Markdown'
---

// 自定义文本和链接
---
prev:
  text: 'Markdown'
  link: '/guide/markdown'
---

// 隐藏上一页
---
prev: false
---

大纲

列出了页面内的各个标题及其对应的链接锚点，允许用户快速浏览和跳转到页面内的不同部分。

yaml 复制代码

---
outline: false  // number | [number, number] | 'deep' | false
---

技术清单

名称	版本	说明
node	v18.16.0	---
vitepress	1.0.0-rc.45	---
vite	---	服务器即时启动，闪电般的热更新，还可以使用基于 `Vite` 生态的插件。
markdown	---	需要了解 `Markdown` 相关语法
vue3	---	直接在 `Markdown` 中使用 `Vue` 语法和组件，或者使用 `Vue` 组件构建自定义主题。

最佳实践

请见下一篇文章，敬请期待....

前端基建必备技能：前端项目文档-初识VitePress

VitePress

安装

配置和API

首页布局

导航栏

代码示例：站点标题和图标

代码示例：本地搜索

代码示例：导航连接

代码示例：国际化

代码示例：主题切换

代码示例：社交链接

主页

页脚

内页布局

侧边栏

代码示例：基本用法

代码示例：多侧边栏

代码示例：可折叠的侧边栏组

最后更新于

编辑链接

上下页链接

大纲

技术清单

最佳实践