VuePress 快速踩坑

04-30

最近有個開源項目非常火，那就是尤小右開發的 VuePress，VuePress 可以讓您非常方便的在 Markdown 文檔中編寫 Vue 代碼，並且 VuePress 對編譯後的 HTML 文件做了一些針對搜索引擎的優化。另外 VuePress 針對 Markdown 文件做了一些擴展使其功能更加強大，本文將圍繞搭建一個 Github 的靜態博客展開。

為項目加入 VuePress

第一步為您的項目安裝 VuePress，如果您的項目代碼中並沒有 package.json文件，請先執行 npm init。

npm install -D vuepress // 或者 yarn add -D vuepress// 在項目根目錄下新加 docs 文件夾mkdir docs// 新建一個 Markdown 文件echo "# Hello VuePress!" > docs/README.md

第二步在 package.json 中加入這些腳本，並運行。

// package.json"scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs"}// 本地運行文檔npm run docs:dev// 編譯打包生產靜態 HTML 文件npm run docs:build

VuePress 對 Markdown 做了一些擴展，使得我們可以在 Markdown 文件中使用 YAML 語法，VuePress 使用 ---來隔離 Markdown 語法。

---// 該語法表示使用當前頁面標題自動生成側邊欄sidebar: auto---

VuePress 基礎配置

通過 VuePress 配置文件我們可以使用一些自定義的功能，譬如添加側邊欄，添加導航欄等。首先在 docs 目錄下新建一個 .vuepress目錄，並在該目錄下方新建 config.js。

VuePress 默認將文件打包在 .vuepress/dist目錄下，我們可以通過 dest屬性修改文件輸出目錄，例如將文件輸出在項目根目錄下的 dist文件夾中。
通過設置 repo屬性，VuePress 會在導航欄中添加一個 Github 倉庫的鏈接。
在 VuePress 中通過設置 title屬性來設置網站的標題，它將會被用作所有頁面標題的前綴，在默認主題下，它將應用在導航欄上。
在使用 VuePress 編寫博客並發布到 Github pages 的時候，我們可能會遇到下圖所顯示的問題，頁面已經有了，但是樣式和 js 沒有載入成功。我們可以通過配置 base 屬性來解決這個問題， base 屬性的默認值是 /。假如您準備將代碼部署到 https://taoxusheng.github.io/mt-blog/ , 那麼 base屬性就應該被設置成 /mt-blog/。注意：base 屬性的值總是以 / 開始並以 / 結束。

// dcos/.vuepress/config.jsmodule.exports = { title: my-blog, // 設置網站標題 dest: ./dist, // 設置輸出目錄 base: /mt-blog/, // 設置站點根路徑 repo: https://github.com/TaoXuSheng/mt-blog // 添加 github 鏈接}

導航欄與側邊欄

在 VuePress 中如果想要為您的網站添加導航欄，可以通過設置 themeConfig.nav 來添加導航鏈接，通過設置 themeConfig.sidebar 屬性來添加側邊欄。如果您的導航是一個下拉列表，可以通過 items 屬性來設置。

// dcos/.vuepress/config.jsmodule.exports = { themeConfig: { // 添加導航欄 nav: [ { text: vue, link: / }, { text: css, link: /blog/ }, { text: js, link: /zhihu/ }, { text: github, // 這裡是下拉列表展現形式。 items: [ { text: focus-outside, link: https://github.com/TaoXuSheng/focus-outside }, { text: stylus-converter, link: https://github.com/TaoXuSheng/stylus-converter } ] } ], // 為以下路由添加側邊欄 sidebar: [/, /git, /vue] }}

有些時候我們可能需要一個多級側邊欄，例如一個博客系統，將一些類似的文章放在相同的目錄下方，我們希望為這些目錄的所有文件都添加側邊欄，就像下面這樣的一個目錄。

docs ├── README.md ├── vue │ ├─ README.md │ ├─ one.md │ └─ two.md └── css ├─ README.md ├─ three.md └─ four.md

對於多級目錄的側邊欄，我們需要用使用對象描述的寫法，下面的 /git/ 表示在 git 目錄，默認指向 /git/README.md 文件。

// dcos/.vuepress/config.jsmodule.exports = { themeConfig: { sidebar: { /vue/: [ one, two ], /css/: [ three, four ] } }}

在 VuePress 中註冊組件

在 VuePress 中編寫 Vue 代碼，和我們通常的編寫單文件的方式一致，有些時候我們有可能需要使用 Vue 的 UI 組件庫。例如 Element，Mint 等，通常我們在項目中使用這些 UI 組件庫的時候，我們都會在 main.js 或 botostrap.js 文件中統一註冊。好在 VuePress 中也支持這種功能，我們可以通過創建一個 .vuepress/enhanceApp.js 文件來做一些應用級別的配置，這個文件 exprot default 一個鉤子函數，在這個鉤子中你可以做一些特殊處理，例如添加全局路由鉤子，註冊外部組件庫。

// .vuepress/enhanceApp.js// 全局註冊 Element 組件庫import Vue from vueimport Element from element-uiimport element-ui/lib/theme-chalk/index.cssexport default ({ Vue, options, router}) => { Vue.use(Element)}

在 Vue 正常開發中，有些時候我們可能會需要做一些自定義的組件，在 VuePress 中我們可以在 .vuepress/components 目錄中編寫我們的自定義組件，VuePress 在編譯時遍歷該目錄中所有的 *.vue 文件，並見它們註冊為全局組件。

// 註冊一個自定義組件// docs/.vuepress/components/hello.vue<template> <div class="cpt-hello">Hello VuePress Demo</div></template>

這樣我們在 Markdown 文件編寫 Vue 代碼的時候就不需要註冊註冊這些組件，邊可以直接在 Markdown 中使用了。

// docs/.vuepress/vue/README.md<template> <div class="test-demo"> {{ msg }} <my-hello></my-hello> <el-button>button</el-button> </div></template><script>export default { data () { return { msg: Hello VuePress! } }}</script>

查看在線示例

部署到 Github pages

當我們將文檔寫好後就到了我們最關心的地方了，怎麼將打包後的代碼推送到遠程倉庫的 gh-pages 分支上，網上應該有很多文章描述怎麼做，但是很多方法比較麻煩，還好有工具已經為我們解決了這個麻煩了。

// 1.下載 gh-pages 包npm install -D gh-pages// 2. 在 package.json 文件上添加腳本命令"scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs", // 上面我修改了 VuePress 的輸出目錄，所以您如果沒有修改 .vuepress/config.js // 的 dest 屬性，應該將這裡的 dist 改為 .vuepress/dist // 注意在使用 gh-pages 的時候請確保你已經添加了 git 遠程倉庫。 "deploy": "gh-pages -d dist", "deploy:build": "npm run docs:build && gh-pages -d dist"}// 3. 打包並推送到 gh-pages 分支npm run deploy:build// 4.打開你的 Github pages, 地址是 https://<yourname>/github.io/<repo>

查看在線示例

總結

相比較 Hexo 而言 VuePress 上手更加容易，功能也更強大，例如在 VuePress 可以註冊自定義組件，而且 VuePress 中編寫 Vue 和平時一樣學習成本幾乎為零。所以如果您正在開源一款 Vue 相關的庫或是其他項目，您都可以使用 VuePress 作為您的文檔編輯工具。雖然並沒有完全將 VuePress 內容講完，學完該篇文章相信你可以對 VuePress 有個大概的了解，您至少可以快速搭建一個博客，如果您想對 VuePress 有更多了解，請參考 Vuepress 中文 API。最後安利一波我正在做的開源項目 stylus-converter，有興趣的同學可以一起參與，祝各位生活愉快，五一小長假玩的開心。