Skip to main content

基础使用

基础使用​

官方文档

1、安装​

$ mkdir vitepress-starter && cd vitepress-starter
$ mkdir docs && echo '# Hello VitePress' > docs/index.md

$ yarn init

# 创建项目
$ yarn add --dev vitepress vue

# 用依赖
yarn add --dev types@node

2、package.json 初始化​

添加"scripts"字段

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",          // 开发
    "docs:build": "vitepress build docs",      // 默认的输出目录将在 ./vitepress/dist
    "docs:serve": "vitepress serve docs"       // 测试
    "docs:serve": "vitepress serve docs --port 8080"       // 测试
  },
  ...
}

3、启动项目​

$ yarn docs:dev

# 默认端口
http://localhost:5173

4、添加其他页面​

.
├─ docs
│  ├─ getting-started.md
│  └─ index.md
└─ package.json

5、添加配置文件​

.
├─ docs
│  ├─ .vitepress            # 这个是默认的配置目录
│  │  └─ config.js|.ts      # 全局配置文件
│  └─ index.md
└─ package.json
// config.js
export default {
  title: 'VitePress',
  base:"路由子路径",
  description: 'Just playing around.'
}

如果您的网站要在子目录 ( ) 中提供服务，那么您https://example.com/subdir/必须'/subdir/'在.basedocs/.vitepress/config.js

示例：如果您使用 Github（或 GitLab）页面并部署到user.github.io/repo/，则将您的设置base为/repo/.

项目结构​

.
├─ docs
│  ├─ .vitepress            # 这个是默认的配置目录
│  │  └─ config.js|.ts      # 全局配置文件
│  ├─ getting-started.md    # md文件
│  └─ index.md              # 首页
└─ package.json

配置使用​

全局配置​

配置文件：./.vitepress/config.js|ts

字段名称类型:默认值说明
titlestring:"VitePress"
titleTemplatestring|false:"xxxxxxxxxxxx"主题名称，最终渲染在title前面: `VitePress
langstring对应标签 <html lang="en-US"/>
headHeadConfig[]:[]将会渲染成<head>内的标签
descriptionstring将会渲染成<meta>标签
basestring:"/"是否存在子路径
appearanceboolean:true是否启用“暗模式”。
ignoreDeadLinksboolean:false设置为true时，如果遇到无效路径也会照常渲染
lastUpdatedboolean:false显示页面文件对应的git commit更新时间
markdownMarkdownOptionmd的解析器相关配置，默认采用markdown-it
outDirstring:./.vitepress/dist构建文件目录
cleanUrlsenum<str>:disabled|without-subfolders|with-subfolders路径去掉.html后缀
themeConfigThemeOptions主题配置

详细文档

主题配置 - themeConfig​

更准确的说是整个页面的布局配置

配置位置：./.vitepress/config.themeConfig

// ./.vitepress/config.ts
import { ThemeOptions } from vitepress

const themeConfig:ThemeOptions = {}

export default themeConfig
字段名称类型:默认值说明
logoThemeableImage:"/logo.svg"logo图片地址，可以是图片会或者svg
siteTitlestring|boolen:"false"导航的title
navNavItem导航列表
sidebarSidebar侧边栏列表
outlineTitlestring侧边栏的标题
socialLinksSocialLink[]社交链接，github|gitee|twitter|qq等等
footerFooter配置页脚
editLinkEditLink在线编辑，这里可以绑定一个匹配式
https://github.com/vuejs/vitepress/edit/main/docs/:path
lastUpdatedTextstring:"Last updated"最后更新的文字描述前缀
carbonAdsCarbonAds广告
docFooterDocFooter上一个和下一个链接上方的文本

详细文档

页面配置​

页面配置可以覆盖任何全局配置和主题配置，拥有最高的优先权，在自定义页面时非常有用

这些配置位于每个页面的md文件中，以三横杠包裹

---
title: Docs with VitePress
editLink: true
---

也可以在md内容中，通过 $变量+{{模板语法}} 的形式动态调用

{{ $frontmatter.title }}
字段名称类型:默认值说明
titlestring:"vitepress"页面标题
titleTemplatestring|boolean于config.titleTemplate等价
descriptionstring于config.description等价
headHeadConfig[]于config.head等价
lastUpdatedboolean:true是否显示当前页面md文件的最后更新时间,等价于config.lastUpdated
layoutstring: `dochome
heroHerolayout该选项仅在设置为home 时生效，对home的一些具体配置
featuresFeature[]layout该选项仅在设置为home 时生效，对home的一些具体配置
asideboolean:true当前页面是否展示右侧组件（目录）

详细文档

MD解析器配置​

VitePress 使用markdown-it作为 Markdown 渲染器。在config里面也可以通过引入markdown-it的一些实例进行操作

const anchor = require('markdown-it-anchor')

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: anchor.permalink.headerLink()
    },

    // options for @mdit-vue/plugin-toc
    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
    toc: { level: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'), opts)
    }
  }
}

详细文档

注意事项​

如果使用 @docsearch/js 和pnpm，需要在pacakage.json中加入以下配置

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search"
    ]
  }
}

github-workflows​

.github/workflows/vitepress-deploy.yml

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: yarn
      - run: yarn install --frozen-lockfile

      - name: Build
        run: yarn docs:build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vitepress/dist

请替换对应的分支名称。例如，如果您要构建的分支是master，那么您应该在上面的文件中main替换为。master

Markdown​

使用md语法的跳转功能，以相对路径的方式编写，最终会被html正确的编译

[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extention -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->

YAML frontmatter​

支持yaml配置内置到md文件内

---
title: Blogging Like a Hacker
lang: en-US
---

在三点虚线之间，您可以设置预定义变量，甚至可以创建自己的自定义变量。这些变量可以通过特殊$frontmatter变量使用。

这是一个如何在 Markdown 文件中使用它的示例：

---
title: Docs with VitePress
editLink: true
---

# {{ $frontmatter.title }}

Guide content

JSON frontmatter 语法​

---
{
  "title": "Blogging Like a Hacker",
  "editLink": true
}
---