前言
來啦老鐵股冗！
接上一篇文章 玩玩 Google Codelabs 放案，今天我們來玩玩另外一個(gè)文檔工具，以期能從中做個(gè)橫向?qū)Ρ饶盘颍褪牵?/p>
-
VuePress
筆者有一點(diǎn) vue 的使用經(jīng)驗(yàn)币励，對 Vue 還是挺喜愛的，而 VuePress 的作者跟 Vue 框架的作者同一個(gè)滋早，都是尤雨溪榄审，頓時(shí)感覺親切無比，你說咱們是不是得拿下它~
網(wǎng)絡(luò)摘抄：VuePress 是尤雨溪（vue.js 框架作者）4月12日發(fā)布的一個(gè)全新的基于 Vue 驅(qū)動的靜態(tài)網(wǎng)站生成器杆麸，實(shí)際上就是一個(gè) vue 的 spa （single page application, 單頁應(yīng)用）應(yīng)用搁进，內(nèi)置 webpack浪感，可以用來寫文檔、博客等饼问。VuePress 專注在以內(nèi)容為中心的靜態(tài)網(wǎng)站上影兽，同時(shí)提供了一些為技術(shù)文檔定制的開箱即用的特性。
主要參考文獻(xiàn)：
整體步驟
- 開發(fā)環(huán)境搭建；
- 配置 VuePress盅视；
- 站點(diǎn)設(shè)置捐名；
- 使用開源主題；
- 生成靜態(tài)文件闹击；
- 簡單對比Google Codelabs 與 VuePress镶蹋；
1. 開發(fā)環(huán)境搭建；
確保安裝了 Node.js赏半，且 Node.js 版本 >= 8.6贺归，安裝過程參考上一篇文章：玩玩 Google Codelabs ；
找一個(gè)地方創(chuàng)建項(xiàng)目断箫，項(xiàng)目名如：vuepress-docs拂酣；
使用 npm 初始化項(xiàng)目；
npm init
- 安裝 vuepress仲义；
npm install --save-dev vuepress
或：
npm install -D vuepress
- 在 package.json 中添加執(zhí)行命令婶熬；
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
此時(shí) package.json 中的內(nèi)容為：
{
"name": "vuepress-docs",
"version": "1.0.0",
"description": "vuepress-docs",
"main": "index.js",
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
"author": "dylanz",
"license": "ISC",
"devDependencies": {
"vuepress": "^1.8.2"
}
}
- Hello VuePress 一下；
- 創(chuàng)建 docs 文件夾光坝；
mkdir docs
- 簡單搞個(gè)頁面尸诽；
echo '# Hello VuePress!' > docs/README.md
- 啟動服務(wù)；
npm run docs:dev
VuePress 會在 http://localhost:8080 啟動一個(gè)熱重載的服務(wù)盯另，即：修改文件性含，保存后會自動更新站點(diǎn)，方便開發(fā)鸳惯。
- 瀏覽器訪問 http://localhost:8080 商蕴；
怎么樣，簡單不芝发，一個(gè)簡單的頁面就這么完成了绪商，我們繼續(xù)學(xué)習(xí)~
2. 配置 VuePress；
- docs 下創(chuàng)建 .vuepress 文件夾辅鲸；
- .vuepress 文件夾下創(chuàng)建 config.js 文件格郁；
網(wǎng)站的title、頁面布局，頁面目錄以及插件的配置例书，都在這個(gè) .vuepress/config.js 文件中锣尉，這個(gè)文件包含網(wǎng)站所有的配置信息；
接下來我們將會修改 .vuepress/config.js 對我們的站點(diǎn)進(jìn)行配置~
3. 站點(diǎn)設(shè)置决采；
- 在 docs/README.md 文件中寫入站點(diǎn)首頁配置自沧，如：
---
home: true
heroImage: /hero.png
heroText: Hero 標(biāo)題
tagline: Hero 副標(biāo)題
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 簡潔至上
details: 以 Markdown 為中心的項(xiàng)目結(jié)構(gòu)，以最少的配置幫助你專注于寫作树瞭。
- title: Vue驅(qū)動
details: 享受 Vue + webpack 的開發(fā)體驗(yàn)拇厢，在 Markdown 中使用 Vue 組件，同時(shí)可以使用 Vue 來開發(fā)自定義主題晒喷。
- title: 高性能
details: VuePress 為每個(gè)頁面預(yù)渲染生成靜態(tài)的 HTML孝偎，同時(shí)在頁面被加載的時(shí)候，將作為 SPA 運(yùn)行凉敲。
footer: MIT Licensed | Copyright ? 2018-present Evan You
---
- 修改 .vuepress/config.js 文件邪媳，如：
module.exports = {
title: 'VuePress 中文文檔',
description: 'VuePress 中文文檔，尤雨溪出品',
head: [
['link', { rel: 'icon', href: '/favicon.ico' }]
],
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://www.baidu.com' },
]
}
}
- .vuepress 文件夾下創(chuàng)建 public 文件夾荡陷，用于存放公共文件，如圖片等迅涮；
- .vuepress/public 文件夾下準(zhǔn)備好主頁 logo 圖片文件废赞，如 hero.png
這時(shí)候你的項(xiàng)目目錄是類似這樣子的：
.
├─ docs
│ ├─ README.md
│ └─ .vuepress
└─ public
└─ hero.png
│ └─ config.js
└─ package.json
- 重新部署站點(diǎn)后，這時(shí)候主頁的樣子：
- 導(dǎo)航欄與側(cè)邊欄配置實(shí)踐叮姑；
這部分參考文章 使用VuePress 搭建文檔網(wǎng)站并進(jìn)行配置 唉地，不難，筆者看到更酷炫的功能传透，等不及了耘沼，先來介紹下面的功能。
4. 使用開源主題朱盐；
VuePress 有個(gè)很強(qiáng)大的功能群嗤，那就是：主題。我們可以自定義主題兵琳，如上述 3 介紹的狂秘，就是一個(gè)簡單的主題，然而上述的主題還是太過于粗糙了躯肌，自己玩玩還是可以者春，項(xiàng)目上有點(diǎn)拿不出手，并且作為初學(xué)者清女，我也不想花太多時(shí)間搞這些钱烟，怎么辦？
還好，神通廣大的網(wǎng)友開發(fā)了各種漂亮的主題拴袭，例如這個(gè)读第，就比較符合我的需求：
- demo: https://xugaoyi.com/
- github：vuepress-theme-vdoing
作為一個(gè)初學(xué)者，咱們先不糾結(jié) VuePress 文檔上的其他知識點(diǎn)稻扬，先探究一下這個(gè) vuepress-theme-vdoing卦方；
1. 快速上手：
# clone the project
git clone https://github.com/xugaoyi/vuepress-theme-vdoing.git
# enter the project directory
cd vuepress-theme-vdoing
# install dependency
npm install # or yarn install
# develop
npm run dev # or yarn dev
2. 執(zhí)行完成后，會看到熟悉的 “success”：
3. 瀏覽器打開 http://localhost:8080/泰佳，酷炫來襲：
4. 頁面很多盼砍，我們以“技術(shù)”為例，截幾個(gè)圖：
5. 簡單對頁面做一下分區(qū)介紹逝她；
第一個(gè)區(qū)域：
這個(gè)區(qū)域是已選中分類的導(dǎo)航欄浇坐，樹狀結(jié)構(gòu)，清晰明了黔宛，同時(shí)支持將該導(dǎo)航欄收縮起來近刘，擴(kuò)大其他區(qū)域的大小臀晃；第二個(gè)區(qū)域：
這個(gè)區(qū)域是文檔瀏覽窗口觉渴，頂部包含幾個(gè)非常貼心的入口，即：“面包屑”導(dǎo)航（可以回到主頁徽惋、跳轉(zhuǎn)至所屬分類主頁面）案淋、作者、寫作日期险绘；
而在區(qū)域的底部，也有一些非常貼心的入口宦棺，如：上次更新時(shí)間瓣距、上一篇與下一篇快速跳轉(zhuǎn)入口、最近更新的文章的入口代咸、github 方面的集成等蹈丸；
-
第三個(gè)區(qū)域：
這個(gè)區(qū)域是當(dāng)前已瀏覽的文章的導(dǎo)航呐芥，可以快速跳轉(zhuǎn)到段落白华，也是十分清晰明了；
頁面的右下角有幾個(gè)入口也是十分貼心贩耐，主要是：回到頁面頂部入口弧腥、皮膚入口
6. 嘗試在這個(gè)主題上做自己的頁面；
- 首先在 docs 文件夾下創(chuàng)建如下目錄與文件潮太；
- 執(zhí)行 npm run dev 命令管搪；
我們執(zhí)行 npm run dev 命令虾攻，執(zhí)行完命令后，會在各新建的文件中自動填充內(nèi)容更鲁，如：
---
title: 第一個(gè)測試文檔
date: 2021-11-22 15:10:05
permalink: /pages/b060ae/
categories:
- 測試
- 子分類A
tags:
-
---
- 目錄頁設(shè)置霎箍；
如果需要展示目錄，則需要在“00.目錄頁”文件夾下創(chuàng)建文件澡为，如 “07.測試.md”（序號不限漂坏，不一定與文件夾序號一致，不過推薦一致媒至，這樣容易維護(hù)）顶别；
我們可以設(shè)置我們的目錄頁，例如我們要用 “07.測試” 文件夾下的內(nèi)容生成目錄頁拒啰，則：
---
pageComponent:
name: Catalogue
data:
key: 07.測試
imgUrl: /img/more.png
description: 這僅僅是個(gè)測試
title: 測試
date: 2020-03-11 21:50:56
permalink: /test
sidebar: false
article: false
comment: false
editLink: false
---
注意：
a. "key: 07.測試" 用于配置要自動生成目錄頁的是哪個(gè)文件夾下的內(nèi)容驯绎；
b. "permalink: /test" 用于配置目錄頁的路由，這個(gè)自定谋旦；
- 編寫文件剩失；
我們可以寫點(diǎn)簡單的內(nèi)容到文件中去，如：
---
title: 第一個(gè)測試文檔
date: 2021-11-21 22:28:42
permalink: /pages/ee1b58/
categories:
- 測試
- 子分類A
tags:
-
author:
name: dylan zhang
link:
---
# 子分類A 測試文檔1
Markdown語法參考
# 一級標(biāo)題
## 二級標(biāo)題
##### 五級標(biāo)題
- 列表第一項(xiàng)
- 列表第二項(xiàng)
1. 有序列表第一項(xiàng)
2. 有序列表第二項(xiàng)
[標(biāo)題](鏈接地址)
*斜體*
**粗體**
> 引用段落
\`\`\`
代碼塊
\`\`\`
- 探索設(shè)置導(dǎo)航欄册着；
修改 docs/.vuepress/config/nav.js 文件拴孤，如：
{
text: '測試',
link: '/test/',
items: [
{ text: '子分類A', link: '/pages/ee1b58/' },
{ text: '子分類B', link: '/pages/fcdab6/' },
{ text: '子分類C', link: '/pages/50475e/' },
],
}
其中：
a. link 值為路由，items內(nèi)的 link 一般設(shè)置子分類文件夾下的第一個(gè)文件中的 permalink 值甲捏；
b. 配置的順序決定了導(dǎo)航欄上的順序乞巧，如我們將“測試”設(shè)置在“技術(shù)”與“更多”之間；
- 瀏覽器打開 http://localhost:8080/ 驗(yàn)證結(jié)果摊鸡；
a. 導(dǎo)航欄入口：
b. 點(diǎn)擊“測試”可進(jìn)入“測試”目錄頁：
c. 點(diǎn)擊“測試”分類下的子分類鏈接或目錄頁的文件鏈接，進(jìn)入文件瀏覽頁面：
- 探索主頁大功能入口設(shè)置蚕冬；
a. 找到 docs/index.md 文件免猾，為“測試”添加主頁入口，添加位置位于“features”字段下囤热，如：
features: # 可選的
- title: 前端
details: JavaScript猎提、ES6、Vue框架等前端技術(shù)
link: /web/ # 可選
imgUrl: /img/web.png # 可選
- title: 頁面
details: html(5)/css(3)旁蔼，前端頁面相關(guān)技術(shù)
link: /ui/
imgUrl: /img/ui.png
- title: 技術(shù)
details: 技術(shù)文檔锨苏、教程、技巧棺聊、總結(jié)等文章
link: /technology/
imgUrl: /img/other.png
- title: 測試
details: 這僅僅是個(gè)測試
link: /test/
imgUrl: /img/other.png
b. 保存后瀏覽器驗(yàn)證：
Ok伞租，我們演示了如何探索式地增加分類、自動生成目錄頁限佩、文件葵诈、主頁大功能入口裸弦，主要就是模仿當(dāng)前的項(xiàng)目文件結(jié)構(gòu)和數(shù)據(jù)，作為快速使用方和調(diào)研目的作喘，這樣已經(jīng)夠了理疙，其他功能點(diǎn)也是類似，請讀者自行探索泞坦，我也會在后續(xù)應(yīng)用場景中探索~
5. 生成靜態(tài)文件窖贤；
執(zhí)行命令：
npm run build
執(zhí)行完命令后，會將產(chǎn)物放至：docs/.vuepress/dist贰锁，與上一篇文章介紹的一樣赃梧，將該文件夾丟到nginx 服務(wù)器上后，就可以部署到遠(yuǎn)程服務(wù)器啦~
6. 簡單對比 Google Codelabs 與 VuePress李根；
1. 開發(fā)環(huán)境搭建槽奕；
VuePress 更優(yōu)。
VuePress 只需要 Node.js 環(huán)境房轿，而 Google Codelabs 不僅需要 Node.js 環(huán)境粤攒，還需要 go 語言環(huán)境、還需要 claat (Codelabs command line tool) 工具囱持。
2. 組織文檔的方式夯接；
VuePress 更優(yōu)。
VuePress 作為文檔空間纷妆，文檔組織具有很強(qiáng)的結(jié)構(gòu)化特點(diǎn)盔几，加上開源主題的應(yīng)用，使文檔空間變得十分強(qiáng)大掩幢。而 Google Codelabs 是比較扁平化的文檔組織方式逊拍，沒有結(jié)構(gòu)化、歸納等特點(diǎn)际邻；
3. 文檔瀏覽體驗(yàn)芯丧；
個(gè)人感覺 VuePress 更優(yōu)。
在文檔瀏覽頁面世曾，VuePress 不僅能瀏覽當(dāng)前頁面缨恒，并且有當(dāng)前分類的導(dǎo)航、當(dāng)前瀏覽頁面的綱要轮听，可以快速跳轉(zhuǎn)到文檔中的節(jié)點(diǎn)骗露。
Google Codelabs 頁面會按編寫設(shè)置，將文檔劃分為不同節(jié)點(diǎn)（類似頁面的綱要）血巍，點(diǎn)擊節(jié)點(diǎn)也可以快速跳轉(zhuǎn)到文檔中的節(jié)點(diǎn)萧锉，但功能相對有限；
4. 文檔瀏覽體驗(yàn)述寡；
個(gè)人感覺 VuePress 更優(yōu)驹暑。
VuePress 文檔的編寫玫恳，與編寫任何 Markdown 文件無異，而 Google Codelabs 則需要按規(guī)則优俘，設(shè)置好哪個(gè)文字作為節(jié)點(diǎn)的 title京办，實(shí)際上 Google Codelabs 節(jié)點(diǎn)的 title 占用了最大號的 Markdown head，如 “# 這是第一個(gè)節(jié)點(diǎn)title”帆焕。
截個(gè)圖做一下對比：
5. 美觀性惭婿；
個(gè)人感覺 VuePress 更優(yōu)。
使用了開源主題前叶雹，VuePress 也不遜于 Google Codelabs财饥，而使用了開源主題后，更是將 Google Codelabs 甩出幾條街折晦。
綜上钥星，不吹不黑，我個(gè)人感覺 VuePress 更勝一籌满着！
當(dāng)然谦炒，不排除 Google Codelabs 可以在某些應(yīng)用場景下應(yīng)用，可能由于筆者見識少哈风喇，請讀者自行選擇~
有興趣的同學(xué)可以訪問以下 demo 進(jìn)行體驗(yàn)哈：
- Google Codelabs: http://clmirror.storage.googleapis.com/index.html
- VuePress（vuepress-theme-vdoing 主題）: https://xugaoyi.com/
另外宁改，我們依然可以用上一篇文章介紹的 Minio 對象存儲服務(wù)，作為圖床魂莫。還有可以使用 Typora 進(jìn)行 Markdown 文件的編寫还蹲，有機(jī)會咱們也可以學(xué)起，nice to have：
好了耙考，今天我們就先聊到這啦谜喊，更多的 VuePress 知識，官網(wǎng)上學(xué)習(xí)哈倦始，有機(jī)會我們再聊聊這方面~
如果本文對您有幫助斗遏，麻煩動動手指點(diǎn)點(diǎn)贊？
非常感謝楣号！
