VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格
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.ioUSERNAME=你的使用者名稱 # git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master # 如果釋出到 https://<USERNAME>.github.io/<REPO>REPO=github上的專案 # git push -f [email protected]:<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元件等，這些功能我也還在摸索，所以大家一定要去看文件!
結語
上面已經寫得儘可能詳細了，我遇到的坑都寫上去了。搭建起來確實很簡單，心動不如行動，隨手花一兩個小時搭建一下又不吃虧，何樂而不為？