VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客
栏目: JavaScript · 发布时间: 6年前
内容简介:VuePress是尤大为了支持 Vue 及其子项目的文档需求而写的一个项目,VuePress界面十分简洁,并且建议先看一下官方文档可能你会搭建出一个类似这样的文档:
VuePress是尤大为了支持 Vue 及其子项目的文档需求而写的一个项目,VuePress界面十分简洁,并且 非常容易上手,一个小时就可以将项目架构搭好 。现在已经有很多这种类型的文档,如果你有写技术文档的项目的话,VuePress绝对可以成为你的备选项之一。
VuePress特性:
- 为技术文档而优化的 内置 Markdown 拓展
- 在 Markdown 文件中使用 Vue 组件的能力
- Vue 驱动的自定义主题系统
- 自动生成 Service Worker
- Google Analytics 集成
- 基于 Git 的 “最后更新时间”
- 多语言支持
- 默认主题包含:
建议先看一下官方文档
效果:
可能你会搭建出一个类似这样的文档:
搭建:
全局安装VuePress
yarn global add vuepress # 或者:npm install -g vuepress 复制代码
新建文件夹
可以手动右键新建,也可以使用下面的命令新建文件夹:
mkdir project 复制代码
项目初始化
进入到 project
文件夹中,使用命令行初始化项目:
yarn init -y # 或者 npm init -y 复制代码
将会创建一个 package.json
文件,长这样子:
{ "name": "project", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" } 复制代码
在project的根目录下新建docs文件夹:
这个文档将作为项目文档的根目录来使用:
mkdir docs 复制代码
在docs文件夹下创建 .vuepress
文件夹:
mkdir .vuepress 复制代码
所有 VuePress 相关的文件都将会被放在这里
在 .vuepress
文件夹下面创建 config.js
:
touch config.js 复制代码
config.js是VuePress必要的配置文件,它导出一个javascript对象。
你可以先加入如下配置:
module.exports = { title: 'Hello VuePress', description: 'Just playing around' } 复制代码
在 .vuepress
文件夹下面创建public文件夹:
mkdir public 复制代码
这个文件夹是用来放置静态资源的,打包出来之后会放在.vuepress/dist/的根目录。
首页(像VuePress文档主页一样)
在docs文件夹下面创建一个 README.md
:
默认的主题提供了一个首页,像下面一样设置 home:true
即可,可以把下面的设置放入 README.md
中,待会儿你将会看到跟 VuePress
一样的主页。
--- home: true heroImage: /logo.jpg actionText: 快速上手 → actionLink: /zh/guide/ features: - title: 简洁至上 details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。 - title: Vue驱动 details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。 - title: 高性能 details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。 footer: MIT Licensed | Copyright © 2018-present Evan You --- 复制代码
ps:你需要放一张图片到public文件夹中。
我们的项目结构已经搭好了:
project ├─── docs │ ├── README.md │ └── .vuepress │ ├── public │ └── config.js └── package.json 复制代码
在 package.json
里添加两个启动命令:
{ "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" } } 复制代码
启动你的VuePress:
默认是 localhost:8080
端口。
yarn docs:dev # 或者:npm run docs:dev 复制代码
构建:
build生成静态的HTML文件,默认会在 .vuepress/dist
文件夹下
yarn docs:build # 或者:npm run docs:build 复制代码
基本配置:
最标准的当然是官方文档,可以自己的需求来配置 config.js
。
可以参考一下我的 config.js
的配置:
module.exports = { title: '网站标题', description: '网站描述', // 注入到当前页面的 HTML <head> 中的标签 head: [ ['link', { rel: 'icon', href: '/favicon.ico' }], // 增加一个自定义的 favicon(网页标签的图标) ], base: '/web_accumulate/', // 这是部署到github相关的配置 下面会讲 markdown: { lineNumbers: true // 代码块显示行号 }, themeConfig: { sidebarDepth: 2, // e'b将同时提取markdown中h2 和 h3 标题,显示在侧边栏上。 lastUpdated: 'Last Updated' // 文档更新时间:每个文件git最后提交的时间 } }; 复制代码
导航栏配置:
module.exports = { themeConfig: { nav:[ { text: '前端算法', link: '/algorithm/' }, // 内部链接 以docs为根目录 { text: '博客', link: 'http://obkoro1.com/' }, // 外部链接 // 下拉列表 { text: 'GitHub', items: [ { text: 'GitHub地址', link: 'https://github.com/OBKoro1' }, { text: '算法仓库', link: 'https://github.com/OBKoro1/Brush_algorithm' } ] } ] } } 复制代码
侧边栏配置:
侧边栏的配置相对麻烦点,我里面都做了详细的注释,仔细看,自己鼓捣鼓捣 就知道怎么搞了。
module.exports = { themeConfig: { sidebar:{ // docs文件夹下面的accumulate文件夹 文档中md文件 书写的位置(命名随意) '/accumulate/': [ '/accumulate/', // accumulate文件夹的README.md 不是下拉框形式 { title: '侧边栏下拉框的标题1', children: [ '/accumulate/JS/test', // 以docs为根目录来查找文件 // 上面地址查找的是:docs>accumulate>JS>test.md 文件 // 自动加.md 每个子选项的标题 是该md文件中的第一个h1/h2/h3标题 ] } ], // docs文件夹下面的algorithm文件夹 这是第二组侧边栏 跟第一组侧边栏没关系 '/algorithm/': [ '/algorithm/', { title: '第二组侧边栏下拉框的标题1', children: [ '/algorithm/simple/test' ] } ] } } } 复制代码
其他:
代码块编译错误:
像下面这段代码会导致编译错误,VuePress会去找里面的变量,把它编译成text:
{{}} 啦 {{}} 复制代码
所以我们的代码块要以这种形式书写:
{{}} 啦 {{}} 复制代码
并且这样也会让我们的代码高亮显示(下图第一个没有高亮,第二个有高亮),阅读体验更好:
自定义容器了解一下:
更改标题:
::: tip 替换tip的标题 这里是内容。 ::: 复制代码
其实文档里有,我这里只是提一下。
支持Emoji
文档中只提了支持Emoji,我在GitHub上找到了Emoji的 列表 ,分享一下。
一个命令行发布到github上:
在 docs/.vuepress/config.js
中设置正确的 base:
如果你打算发布到 https://<USERNAME>.github.io/
,则可以省略这一步,因为 base 默认即是 "/"
。
如果你打算发布到 https://<USERNAME>.github.io/<REPO>/
(也就是说你的仓库在 https://github.com/<USERNAME>/<REPO>
),则将 base 设置为 "/<REPO>/"
。
module.exports = { base: '/test/', // 比如你的仓库是test } 复制代码
创建脚步文件:
在 project
的根目录下,创建一个 deploy.sh
文件:
#!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 npm run docs:build # 进入生成的文件夹 cd docs/.vuepress/dist # 如果是发布到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 如果发布到 https://<USERNAME>.github.io USERNAME=你的用户名 # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master # 如果发布到 https://<USERNAME>.github.io/<REPO> REPO=github上的项目 # git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages cd - 复制代码
设置package.json:
{ "scripts": { "d": "bashdeploy.sh" } }
部署:
然后你每次可以运行下面的命令行,来把最新更改推到 github
上:
npm run d 复制代码
如果你对运行项目和构建项目的命令行觉得很烦,你也可以像我这么做:
"scripts": { "dev": "vuepress dev docs", // 本地运行项目 npm run dev "build": "vuepress build docs", // 构建项目 nom run build "d": "bash deploy.sh" // 部署项目 npm run d }, 复制代码
更多:
实际上VuePress的配置、用法还有很多,像还可以配置PWA,以及在markdown里面使用Vue组件等,这些功能我也还在摸索,所以大家一定要去看文档!
结语
上面已经写得尽可能详细了,我遇到的坑都写上去了。搭建起来确实很简单,心动不如行动,随手花一两个小时搭建一下又不吃亏,何乐而不为?
以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网
猜你喜欢:- ShowDoc 2.8.3 发布,IT 团队的在线 API 文档、技术文档工具
- 开源 | ShowDoc:一个非常适合 IT 团队的在线 API 文档、技术文档工具
- 如何撰写技术文档
- ShowDoc v2.7.1 发布,IT 团队的在线 API 文档、技术文档工具
- ShowDoc v2.8.0 发布, IT 团队的在线 API 文档、技术文档工具
- ShowDoc v2.8.2 发布, IT 团队的在线 API 文档、技术文档工具
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
Java in a Nutshell, 6th Edition
Benjamin J Evans、David Flanagan / O'Reilly Media / 2014-10 / USD 59.99
The latest edition of Java in a Nutshell is designed to help experienced Java programmers get the most out of Java 7 and 8, but it's also a learning path for new developers. Chock full of examples tha......一起来看看 《Java in a Nutshell, 6th Edition》 这本书的介绍吧!
HEX CMYK 转换工具
HEX CMYK 互转工具
HEX HSV 转换工具
HEX HSV 互换工具