前言

vitepress是在vite上构建的，快速建站工具。可以很轻松的创建文档应用，接下来介绍如何使用vitepress。因为vitepress的文档内容较多且支持自定义，我这里只列举了平时使用最多的几个功能和vitepress的默认设置，具体请参考官方文档vitepress.vuejs.org/。关于vitepress更多丰富的功能会在后续文章中补上。

构建`vitepress`工程

创建`vitepress-app`工程

mkdir vitepress-app
cd vitepress-app
npm init
npm install vitepress --save

执行上述代码，创建vitepress-app工程，初始化npm,安装vitepress

hello world

mkdir docs
echo '# hello world' > docs/index.md

创建docs目录，添加index.md，内容为'# hello world'

追加脚本

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  },

在/package.json中添加启动和打包脚本。docs:dev是启动开发版，build是打包，serve是把打包结果在本地服务端运行。

效果

npm run docs:dev运行，效果图如下：

默认布局

创建路由

构建如上目录结构，访问

http://localhost:3000/about/

http://localhost:3000/contact/

http://localhost:3000/guide

注意：/about/和/contact/会默认加载目录下的index.md文件，所以路由不能输入http://localhost:3000/about, 不然会访问about.html文件。/guide反之亦然。

创建导航栏

创建/docs/vitepress/config.js，代码如下

export default {
    title: 'VitePress App',
    themeConfig: {
        nav: [
            { text: 'Home', link: '/' },
            { text: 'About', link: '/about/' },
            { text: 'Contact', link: '/contact/' }
        ],
        sidebar: []
    }
}

效果：

创建侧边栏

同上

export default {
    title: 'VitePress App',
    themeConfig: {
        nav: [
            { text: 'Home', link: '/' },
            { text: 'About', link: '/about/' },
            { text: 'Contact', link: '/contact/' }
        ],
        sidebar: [
            { text: 'About1', link: '/about/about1' },
            { text: 'About2', link: '/about/about2' },
            { text: 'Contact1', link: '/contact/contact1' },
            { text: 'Contact2', link: '/contact/contact2' }
        ]
    }
}

也可以修改成如下在不同路由下渲染不同的侧边栏：

export default {
    title: 'VitePress App',
    themeConfig: {
        nav: [
            { text: 'Home', link: '/' },
            { text: 'About', link: '/about/about1' },
            { text: 'Contact', link: '/contact/contact1' }
        ],
        sidebar: {
            '/about/': [
                { text: 'About1', link: '/about/about1' },
                { text: 'About2', link: '/about/about2' }
            ],
            '/contact/': [
                { text: 'Contact1', link: '/contact/contact1' },
                { text: 'Contact2', link: '/contact/contact2' }
            ]
        }
    }
}

创建首页

YAML是一种标记语言，缩进表示层级关系是这种标记语言的特点。vitepress在md文档的开头接收YAML的语法。但是需要三个短横线包裹。

/docs/index.md修改如下：

---
home: true
heroImage: /logo.png
heroAlt: Logo image
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started
actionLink: /about/about1
features:
  - title: Simplicity First
    details: Minimal setup with markdown-centered project structure helps you focus on writing.
  - title: Vue-Powered
    details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
  - title: Performant
    details: VitePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2019-present Evan You
---

效果：

静态资源

上图中的logo资源没有，我们需要添加它。创建/docs/public/logo.png如下目录。静态资源文件的处理方式见vitepress.vuejs.org/guide/asset…

Markdown拓展

自定义容器

::: tip
This is a tip
:::

::: info
This is an info box
:::

::: warning
This is a warning
:::

::: danger
This is a dangerous warning
:::

在md文件中如下包裹文本字段会对应不同的样式效果。

代码块高亮

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

{4}指定代码块第四行高亮，同理还有

{5-8}, {3-10}, {10-17}
{4,7,9}
{4,7-13,16,23-27,40}

Frontmatter

修改/docs/about/about1.md如下：

---
title: about1
navbar: false
---


# {{ $frontmatter.title }}

以上通过YAML传递局部变量title，并在about1.html隐藏navbar。更多配置见vitepress.vuejs.org/guide/front…

部署

npm run docs:build

docs:build打包工程。vitepress还支持github ci配置，详情见vitepress.vuejs.org/guide/deplo…

如何使用vitepress创建基本的文档应用？

前言

构建vitepress工程

创建vitepress-app工程