前言
VuePress是尤大為了支持 Vue 及其子項(xiàng)目的文檔需求而寫的一個(gè)項(xiàng)目僧鲁，VuePress界面十分簡(jiǎn)潔，并且非常容易上手掸掏，一個(gè)小時(shí)就可以將項(xiàng)目架構(gòu)搭好」停現(xiàn)在已經(jīng)有很多這種類型的文檔薪韩，如果你有寫技術(shù)文檔的項(xiàng)目的需求，VuePress絕對(duì)可以成為你的備選項(xiàng)之一捌锭。
VuePress特性：
- 為技術(shù)文檔而優(yōu)化的 內(nèi)置 Markdown 拓展
- 在 Markdown 文件中使用 Vue 組件的能力
- Vue 驅(qū)動(dòng)的自定義主題系統(tǒng)
- 自動(dòng)生成 Service Worker
- Google Analytics 集成
- 基于 Git 的 “最后更新時(shí)間”
- 多語(yǔ)言支持
- 默認(rèn)主題包含：
建議先看一下官方文檔1.x
環(huán)境準(zhǔn)備
Windows
- 安裝 cmder,使用教程
解壓完成后復(fù)制其路徑地址躬存，將其添加到環(huán)境變量。
使用Win + R鍵快速啟動(dòng)cmder舀锨，若成功則添加環(huán)境變量成功岭洲。 - 安裝 git
安裝包一路next即可，在桌面上右鍵出現(xiàn)git bash here或命令行中輸入git --version能夠得到具體的版本信息則安裝成功坎匿。 - 安裝 nodejs
安裝包同樣一路next即可盾剩，在命令行輸入node -v雷激，若得到具體版本信息則安裝成功。 - 安裝 yarn
安裝完成后告私，在命令行輸入yarn --version屎暇， 若得到具體版本信息則安裝成功。 - 創(chuàng)建項(xiàng)目
- 創(chuàng)建項(xiàng)目可以分為兩種形式：
- 遠(yuǎn)程倉(cāng)庫(kù)
# xxx 為你的遠(yuǎn)程倉(cāng)庫(kù)連接 git clone xxx cd your_project_name npm init -y - 本地倉(cāng)庫(kù)
# xxx 為你的遠(yuǎn)程倉(cāng)庫(kù)連接 npm init your_project_name -y cd your_project_name git remote add origin xxx
- 遠(yuǎn)程倉(cāng)庫(kù)
- 安裝 vuepress
# 全局安裝
yarn global add vuepress@next # 或者：npm install -g vuepress@next
# 本地安裝
yarn add -D vuepress@next # 或者：npm install -D vuepress@next
- 配置
package.json腳本
如果你的文檔不是在 docs 下驻粟，可以按照你的設(shè)置來(lái)：
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
上面配置完后根悼，可以進(jìn)行測(cè)試：
yarn docs:dev # 或者：npm run docs:dev
若能在瀏覽器中正常訪問(wèn)，則表示安裝成功蜀撑。
搭建及優(yōu)化
1.配置路由及導(dǎo)航
關(guān)于文件是如何渲染為對(duì)應(yīng)的路由的：
| 文件的相對(duì)路徑 | 頁(yè)面路由地址 |
|---|---|
| /README.md | / |
| /guide/README.md | /guide/ |
| /config.md | /config.html |
- 了解了這個(gè)基本的概念后挤巡，就可以去配置對(duì)應(yīng)的導(dǎo)航了。具體的導(dǎo)航欄配置介紹可以看 官方文檔
- 在實(shí)踐后發(fā)現(xiàn)酷麦，若將所有內(nèi)容放置在
docs/.vuepress/config.js下將會(huì)很臃腫矿卑，難以閱讀與維護(hù)，推薦將其分離開(kāi)沃饶，在根目錄下新建一個(gè)config文件夾：
// docs/.vuepress/config.js
const navConf = require('../../config/navConf.js');
module.exports = {
themeConfig: {
nav: navConf
},
}
- 舉個(gè)例子：
module.exports = [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://google.com' },
{
text: 'Languages',
items: [
{ text: 'Chinese', link: '/language/chinese/' },
{ text: 'Japanese', link: '/language/japanese/' }
]
},
{
text: '關(guān)于',
items: [
{ text: '關(guān)于我', items: [
{ text: '個(gè)人介紹', link: '/about/SelfIntroduction/' },
]},
{ text: '個(gè)人簡(jiǎn)歷', items: [
{ text: '簡(jiǎn)歷', link: '/about/CurriculumVitae/' }
]}
]
}
]
2.配置側(cè)邊欄
- 側(cè)邊欄比導(dǎo)航欄要更為繁瑣一些母廷。具體的導(dǎo)航欄配置介紹可以看 官方文檔。
- 首先在 docs 文件夾下新建你需要的目錄及文件：
about
├── CurriculumVitae
│ ├── viate1.md
│ ├── viate2.md
│ ├── viate3.md
│ └── README.md
├── SelfIntroduction
├── self1.md
└── README.md
- 配置
config文件糊肤，當(dāng)文章很多的情況下琴昆，還集中在 config 文件中，那就得炸了：
// docs/.vuepress/config.js
const sidebarConf = require('../../config/sidebarConf/index.js');
module.exports = {
themeConfig: {
sidebar: sidebarConf
},
}
- 文章需要進(jìn)行分類馆揉，所以會(huì)分成更多的子文件业舍，通過(guò) index.js 進(jìn)行管理：
# config/sidebarConf
sidebarConf
├── about
│ ├── algorithm
│ │ └── index.js
│ ├── clean
│ │ └── index.js
│ ├── git
│ │ └── index.js
│ └── interview
│ └── index.js
// config/sidebarConf/index.js
const CurriculumVitae = require('./about/CurriculumVitae/index');
const SelfIntroduction = require('./about/SelfIntroduction/index');
module.exports = {
'/about/CurriculumVitae/': CurriculumVitae,
'/about/SelfIntroduction/': SelfIntroduction,
// 根目錄下的 sidebar, 對(duì)于所有未匹配到的都會(huì)應(yīng)用該 sidebar
// '/': [''] // 此處選擇禁用
};
// config/sidebarConf/about/CurriculumVitae/index.js
const utils = require('../../../../utils/index');
const children = ['', 'viate1', 'viate2','viate3']
module.exports =[
utils.genSidebar('個(gè)人簡(jiǎn)歷', children, false ),
];
//genSidebar 函數(shù)：
// utils/index.js
const utils = {
//生成側(cè)邊欄
genSidebar: function(title, children = [''], collapsable = true, sidebarDepth = 1) {
return {
title, // 必要的
children,
collapsable, // 可選的, 默認(rèn)值是 true,
sidebarDepth, // 可選的, 默認(rèn)值是 1
}
}
};
module.exports = utils;
3.SEO配置
- 基本配置可以幫助我們做好網(wǎng)站的 SEO，更容易被搜索到把介。具體的基本配置介紹可以看 官方文檔
// docs/.vuepress/config.js
module.exports = {
title: '飛躍高山與大洋的魚(yú)',
description: '飛躍高山與大洋的魚(yú)的文檔, vuepress 文檔',
}
4.更新時(shí)間與靜態(tài)資源
- 更新時(shí)間勤讽，如果按照文檔進(jìn)行配置的話時(shí)間格式是非中文的風(fēng)格蟋座，解決很簡(jiǎn)單：
// 添加多語(yǔ)言拗踢，改為國(guó)內(nèi)即可
module.exports = {
locales: {
'/': {
lang: 'zh-CN',
}
},
themeConfig: {
lastUpdated: '上次更新',
},
}
- 所有的靜態(tài)資源都需要放置在 .vuepress/public 目錄下，你也可以為它們建立分類文件夾（這里不好的效果是在預(yù)覽本地的 Markdown 文件時(shí)無(wú)法看到圖片）：
public
├── apple-touch-icon.png
├── app.png
├── base
│ └── interview
│ └── 1468042984788341.png
├── favicon-32x32.png
├── favicon.ico
├── FrontEnd
│ └── javascript
│ ├── es6_20190112123602.png
│ └── es6_20190112124206.png
├── manifest.json
5.部署到 github 并關(guān)聯(lián)到自定義域名
具體的部署介紹可以看官方文檔
我這里沒(méi)有自定義域名向臀，使用的githuPage,發(fā)布到的是https://<USERNAME>.github.io/yufanBlog/,
所以需要再配置文件設(shè)置base屬性巢墅，指定yufanBlog倉(cāng)庫(kù)
# .vurpress/config.js
base: "/yufanBlog/",
#!/usr/bin/env sh
# 確保腳本拋出遇到的錯(cuò)誤
set -e
# 生成靜態(tài)文件
npm run docs:build
# 進(jìn)入生成的文件夾
cd docs/.vuepress/dist
# 如果是發(fā)布到自定義域名
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果發(fā)布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:shanyuhai123/documents.git master:gh-pages
cd -
6. 添加 Git 倉(cāng)庫(kù)和編輯鏈接
參考文檔同上:
// docs/.vuepress/config.js
module.exports = {
themeConfig: {
// 你的 Git 項(xiàng)目地址，添加后會(huì)在導(dǎo)航欄的最后追加
repo: 'shanyuhai123/documents',
// 啟用編輯
editLinks: true,
// 編輯按鈕的 Text
editLinkText: '編輯文檔券膀！',
// 編輯文檔的所在目錄
docsDir: 'docs',
// 假如文檔放在一個(gè)特定的分支下：
// docsBranch: 'master',
},
}
7.域名解析
關(guān)于域名解析詳情可以去看 視頻 （第五個(gè)視頻中的解析方式存在問(wèn)題）君纫。
解析方式需要改為 CNAME 的形式：
