详解:使用 vuepress 实现项目文档

505 阅读6分钟

前言

对于前端初学者,VuePress 的官方文档阅读起来可能令人产生不少疑惑,本篇文章对文档内容删繁就简、尽可能多的使用图文并茂方式,记录如何使用 VuePress 实现一个文档网站。您只需要有一点前端工程化的开发经验,如 npmnode 的安装与简单使用、了解 markdown 语法、了解 vue 的基础语法(非必须),通过以下教程,就可实现属于自己的项目文档网站。

本项目基于 VuePress v1.x 版本。

一、 VuePress 介绍

VuePress 是一个极简静态网站生成器,其支持的 markdown 语法可以快捷实现文档网站的开发。 以下是我使用其实现的一个移动端组件库的项目文档:文档地址

二、初始化项目

1. 创建目录

在磁盘合适位置,新建文件夹,本项目示例文件夹名称约定为 docs-demo

2. 项目安装

  1. 进入 docs-demo 文件夹,执行 npm 项目初始化命令,生成 package.json 文件:

    npm init
    

    按提示填入项目与个人信息(这一步不是必须的,安装 vuepress 时会自动生成 package.json

  2. 执行项目安装命令:

    npm install -D vuepress
    

    安装完成后,在 docs-demo 文件夹下新建 /docs/readme.md 文件,文件结构如下:

    ├─ docs
    │  └── readme.md
    ├─ node_modules
    └─ package.json
    

    readme.md 文件即为文档的首页,我们可以使用 markdown 语法(也支持 HTML)写入需要展示的内容。

  3. 设置 package.json

    • 安装后 package.json 内容如下(vuepress 版本可能有差异),我们需要给它加上项目启动命令:
    {
      // 默认内容
      "devDependencies": {
        "vuepress": "^1.9.7"
      },
      // 启动命令
      "scripts": {
        "dev": "vuepress dev docs",
        "build": "vuepress build docs"
      }
    }
    

    注:启动命令名称是可以自定义的,如 { "docs:dev": "vuepress dev docs" }

  4. 启动项目

    npm run dev
    

    执行后,项目默认会在 8080 端口(如果端口未被占用)运行,我们在浏览器中输入 http://localhost:8080,即可看到运行的网页。

三、页面设置

1. 首页设置

vuepress 官方提供了一个首页模板配置,基础配置如下,将其复制到 /docs/readme.md 文件中。
此时,我们需要重新运行 npm run dev 命令,否则不会生效,如果使用 markdown 语法对 .md 内容进行修改,则不需要重新运行。

---
home: true
heroImage: /logo.png
actionText: 快速上手 
actionLink: /guide/
features:
lang: zh-CN
footer: MIT Licensed | Copyright © 20XX-2022 xxx.com 版权所有
---

运行效果如下:

可以看到,logo 图片裂了,接下来我们将设置 logo 图与 快速上手 链接等文件,在此之前,我们先了解下这些文件存放的目录以及如何配置其它文档页面。
关于首页更多设置项,请查看官方文档

2. 文档书写

对于 .md 文件,我们可以通过 markdown 语法去书写文档内容,其基本语法如下:

image.png

四、目录介绍

按如下结构创建文件夹与文件,* 标识为必要文件:

├── docs
│   ├── .vuepress              // * 项目主体配置目录
│   │   ├── components         // vue 组件,该目录下组件会被自动注册为全局组件
│   │   ├── theme              // 主题,可根据需求开发,后面会详细说明
│   │   ├── public             // * 静态资源目录,如logo图
│   │   ├── styles             // 存放需要定制的样式
│   │   │   ├── index.styl     // 会覆盖全局的样式
│   │   │   └── palette.styl   // 用于配置项目主题色
│   │   ├── config.js          // * 项目配置文件
│   │   └── enhanceApp.js      // 引入vue三方组件等
│   ├── readme.md              // 首页内容文件
│   ├── guide
│   │   └── readme.md          // 默认首页 "快速上手" 按钮的跳转页面
│   ├── page                   // 其它页面
│   └── ...                    // 更多页面
│ 
└── package.json

1. public 文件夹

该文件夹存放静态资源文件,我们将 logo.pngfavicon.ico 文件放入到 public 文件夹中,首页的缺失的 logo 与浏览器标签页的图标将会正常显示出来。

2. config.js 配置

注意:config.js 文件每次修改,都需要重新启动项目

module.exports = {
  title: '文档标题',
  base: '/',   // 如果项目域名访问地址在子文件夹时需要配置
  description: '文档描述',
  dest: 'dist',  // npm run build 打包文件存放路径
  plugins: ['@vuepress/back-to-top'], // 启用返回顶部按钮
  themeConfig: {
    logo: '/logo.png',                // 项目logo图地址
    smoothScroll: true,               // 开启平滑滚动

    // 顶部导航栏
    nav: [
      { text: '介绍', link: '/guide/' },
      { text: '作者', link: 'https://ixook.com' },
      { text: 'GitHub', link: 'https://github.com/NameLi/muying-weapp' },
    ],

    sidebarDepth: 0,  // 侧边栏展开深度

    // 左侧导航栏
    // 注意,readme.md 文件名与文件后缀名可省略
    sidebar: [
      {
        title: '介绍',
        collapsable: false,
        children: [
          ['/guide/', '介绍'],
          ['/guide/markdown', 'markdown 语法']
        ]
      },

      {
        title: '更多内容',
        collapsable: false,
        children: [
          ['/page/', '更多内容']
        ]
      },
    ]
  }
}

效果如下所示:
配置文件效果图.png

更多配置项,请查看官方文档

五、自定义组件

vuepressmarkdown 中支持 vue 组件功能。

1. 组件的实现

vuepress 中实现 vue 组件与 vue-cli 中基本一致,接下来我们实现一个简单的 tag 标签组件,在 .vuepress/components 目录下,新建一个 tag.vue 文件,代码如下:

<template>
  <div class="tag">
    <slot />
  </div>
</template>

<script>
export default {
  name: "tag",
};
</script>
// 样式内容略

2. 组件的使用

.vuepress/components 目录下的组件会被自动注册为全局组件,无需手动引入组件即可使用。

<tag>标签</tag>

更多设置,请查看官方文档

六、使用三方组件

VuePress 支持使用 Vue 的三方组件功能,我们以 element-ui 组件库为例。

1. 组件库安装

npm i element-ui -S

如果组件库安装完后重启项目报 Cannot find module 'core-js/library/fn/object/assign 错误,请执行 npm install async-validator@1.11.5 安装相关支持文件。

2. 组件库配置

编辑 /.vuepress/enhanceApp.js 文件,引入组件库:

import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
Vue.use(ElementUI)

3. 组件的使用

vue 中使用方式一致,在 .md 文件中写相关内容即可,示例如下:

### 组件的使用

<template>
  <el-button @click="showMessage">{{message}}</el-button>
</template>

<script>
export default {
  data () {
    return {
      message: 'this is a button'
    }
  },
  methods: {
    showMessage() {
      this.$message.success('success');
    }
  }
}
</script>

运行效果如下,我们点击按钮,会弹出提示信息: image.png

更多用法,请查看 官方文档

八、文档发布

执行打包命令:

npm run build

打包后 /dist 文件中的 .html 文件无法直接在浏览器中预览,我们可以使用 vscode 编辑器安装 Live Server 插件后,用编辑器打开 /dist 文件夹,点击编辑器右下角的 Go Live,即可启动一个端口为 5050 的服务,来预览生成的文档。
当然,你可以根据自己的需求,将文档发布到自己的服务器或者三方如 github page 等地方,在此不做赘述。

结束语

本篇文章主要介绍了如何使用 vuepress 生成文档网站的简单流程,其基本满足了日常的文档网站需求。如需要对网站样式或页面主题进行调整,请关注我的下一篇文章,我将会介绍如何实现自定义首页、文档左侧菜单与右侧 iframe 页面通信等功能。