前言
对于前端初学者,VuePress
的官方文档阅读起来可能令人产生不少疑惑,本篇文章对文档内容删繁就简、尽可能多的使用图文并茂方式,记录如何使用 VuePress
实现一个文档网站。您只需要有一点前端工程化的开发经验,如 npm
、node
的安装与简单使用、了解 markdown
语法、了解 vue
的基础语法(非必须),通过以下教程,就可实现属于自己的项目文档网站。
本项目基于 VuePress v1.x
版本。
一、 VuePress 介绍
VuePress
是一个极简静态网站生成器,其支持的 markdown
语法可以快捷实现文档网站的开发。
以下是我使用其实现的一个移动端组件库的项目文档:文档地址
二、初始化项目
1. 创建目录
在磁盘合适位置,新建文件夹,本项目示例文件夹名称约定为 docs-demo
2. 项目安装
-
进入
docs-demo
文件夹,执行npm
项目初始化命令,生成package.json
文件:npm init
按提示填入项目与个人信息(这一步不是必须的,安装
vuepress
时会自动生成package.json
) -
执行项目安装命令:
npm install -D vuepress
安装完成后,在
docs-demo
文件夹下新建/docs/readme.md
文件,文件结构如下:├─ docs │ └── readme.md ├─ node_modules └─ package.json
readme.md
文件即为文档的首页,我们可以使用markdown
语法(也支持HTML
)写入需要展示的内容。 -
设置
package.json
- 安装后
package.json
内容如下(vuepress
版本可能有差异),我们需要给它加上项目启动命令:
{ // 默认内容 "devDependencies": { "vuepress": "^1.9.7" }, // 启动命令 "scripts": { "dev": "vuepress dev docs", "build": "vuepress build docs" } }
注:启动命令名称是可以自定义的,如
{ "docs:dev": "vuepress dev docs" }
。 - 安装后
-
启动项目
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
语法去书写文档内容,其基本语法如下:
四、目录介绍
按如下结构创建文件夹与文件,*
标识为必要文件:
├── 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.png
与 favicon.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/', '更多内容']
]
},
]
}
}
效果如下所示:
更多配置项,请查看官方文档
五、自定义组件
vuepress
的 markdown
中支持 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>
运行效果如下,我们点击按钮,会弹出提示信息:
更多用法,请查看 官方文档
八、文档发布
执行打包命令:
npm run build
打包后 /dist
文件中的 .html
文件无法直接在浏览器中预览,我们可以使用 vscode
编辑器安装 Live Server
插件后,用编辑器打开 /dist
文件夹,点击编辑器右下角的 Go Live
,即可启动一个端口为 5050
的服务,来预览生成的文档。
当然,你可以根据自己的需求,将文档发布到自己的服务器或者三方如 github page
等地方,在此不做赘述。
结束语
本篇文章主要介绍了如何使用 vuepress
生成文档网站的简单流程,其基本满足了日常的文档网站需求。如需要对网站样式或页面主题进行调整,请关注我的下一篇文章,我将会介绍如何实现自定义首页、文档左侧菜单与右侧 iframe
页面通信等功能。