最近有個(gè)開源項(xiàng)目非常火，那就是尤小右開發(fā)的 VuePress，VuePress 可以讓您非常方便的在 Markdown 文檔中編寫 Vue 代碼，并且 VuePress 對(duì)編譯后的 HTML 文件做了一些針對(duì)搜索引擎的優(yōu)化。另外 VuePress 針對(duì) Markdown 文件做了一些擴(kuò)展使其功能更加強(qiáng)大，本文將圍繞搭建一個(gè) Github 的靜態(tài)博客展開。

為項(xiàng)目加入 VuePress

第一步為您的項(xiàng)目安裝 VuePress，如果您的項(xiàng)目代碼中并沒有 package.json文件，請(qǐng)先執(zhí)行 npm init。

npm install -D vuepress // 或者 yarn add -D vuepress

// 在項(xiàng)目根目錄下新加 docs 文件夾
mkdir docs

// 新建一個(gè) Markdown 文件
echo "# Hello VuePress!" > docs/README.md

第二步在 package.json 中加入這些腳本，并運(yùn)行。

// package.json
"scripts": {
 "docs:dev": "vuepress dev docs",
 "docs:build": "vuepress build docs"
}

// 本地運(yùn)行文檔
npm run docs:dev

// 編譯打包生產(chǎn)靜態(tài) HTML 文件
npm run docs:build

VuePress 對(duì) Markdown 做了一些擴(kuò)展，使得我們可以在 Markdown 文件中使用 YAML 語(yǔ)法，VuePress 使用 ---來隔離 Markdown 語(yǔ)法。

---
// 該語(yǔ)法表示使用當(dāng)前頁(yè)面標(biāo)題自動(dòng)生成側(cè)邊欄
sidebar: auto
---

VuePress 基礎(chǔ)配置

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

1. VuePress 默認(rèn)將文件打包在 .vuepress/dist目錄下，我們可以通過 dest屬性修改文件輸出目錄，例如將文件輸出在項(xiàng)目根目錄下的 dist文件夾中。
2. 通過設(shè)置 repo屬性，VuePress 會(huì)在導(dǎo)航欄中添加一個(gè) Github 倉(cāng)庫(kù)的鏈接。
3. 在 VuePress 中通過設(shè)置 title屬性來設(shè)置網(wǎng)站的標(biāo)題，它將會(huì)被用作所有頁(yè)面標(biāo)題的前綴，在默認(rèn)主題下，它將應(yīng)用在導(dǎo)航欄上。
4. 在使用 VuePress 編寫博客并發(fā)布到 Github pages 的時(shí)候，我們可能會(huì)遇到下圖所顯示的問題，頁(yè)面已經(jīng)有了，但是樣式和 js 沒有加載成功。我們可以通過配置 base 屬性來解決這個(gè)問題， base 屬性的默認(rèn)值是 /。假如您準(zhǔn)備將代碼部署到 taoxusheng.github.io/mt-blog/ , 那么 base屬性就應(yīng)該被設(shè)置成 /mt-blog/。注意：base 屬性的值總是以 / 開始并以 / 結(jié)束。

// dcos/.vuepress/config.js
module.exports = {
 title: 'my-blog', // 設(shè)置網(wǎng)站標(biāo)題
 dest: './dist'，  // 設(shè)置輸出目錄
 base: '/mt-blog/'，// 設(shè)置站點(diǎn)根路徑
 repo: 
 'https://github.com/TaoXuSheng/mt-blog' // 添加 github 鏈接
}

導(dǎo)航欄與側(cè)邊欄

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

// dcos/.vuepress/config.js
module.exports = {
 themeConfig: {
  // 添加導(dǎo)航欄
  nav: [
   { text: 'vue', link: '/' },
   { text: 'css', link: '/blog/' },
   { text: 'js', link: '/zhihu/' },
   {
    text: 'github',
    // 這里是下拉列表展現(xiàn)形式。
    items: [
     { text: 'focus-outside', link: 'https://github.com/TaoXuSheng/focus-outside' },
     { text: 'stylus-converter', link: 'https://github.com/TaoXuSheng/stylus-converter' },
    ]
   }
  ],
  // 為以下路由添加側(cè)邊欄
  sidebar: ['/', '/git', '/vue']
 }
}

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

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

對(duì)于多級(jí)目錄的側(cè)邊欄，我們需要用使用對(duì)象描述的寫法，下面的 /git/ 表示在 git 目錄，默認(rèn)指向 /git/README.md 文件。

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

在 VuePress 中注冊(cè)組件

在 VuePress 中編寫 Vue 代碼，和我們通常的編寫單文件的方式一致，有些時(shí)候我們有可能需要使用 Vue 的 UI 組件庫(kù)。例如 Element，Mint 等，通常我們?cè)陧?xiàng)目中使用這些 UI 組件庫(kù)的時(shí)候，我們都會(huì)在 main.js 或 botostrap.js 文件中統(tǒng)一注冊(cè)。好在 VuePress 中也支持這種功能，我們可以通過創(chuàng)建一個(gè) .vuepress/enhanceApp.js 文件來做一些應(yīng)用級(jí)別的配置，這個(gè)文件 exprot default 一個(gè)鉤子函數(shù)，在這個(gè)鉤子中你可以做一些特殊處理，例如添加全局路由鉤子，注冊(cè)外部組件庫(kù)。

// .vuepress/enhanceApp.js
// 全局注冊(cè) Element 組件庫(kù)
import Vue from 'vue'
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({
 Vue,
 options,
 router
}) => {
 Vue.use(Element)
}

在 Vue 正常開發(fā)中，有些時(shí)候我們可能會(huì)需要做一些自定義的組件，在 VuePress 中我們可以在 .vuepress/components 目錄中編寫我們的自定義組件，VuePress 在編譯時(shí)遍歷該目錄中所有的 *.vue 文件，并見它們注冊(cè)為全局組件。

// 注冊(cè)一個(gè)自定義組件
// docs/.vuepress/components/hello.vue
<template>
 <div class="cpt-hello">Hello VuePress Demo</div>
</template>

這樣我們?cè)?Markdown 文件編寫 Vue 代碼的時(shí)候就不需要注冊(cè)注冊(cè)這些組件，邊可以直接在 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

當(dāng)我們將文檔寫好后就到了我們最關(guān)心的地方了，怎么將打包后的代碼推送到遠(yuǎn)程倉(cāng)庫(kù)的 gh-pages 分支上，網(wǎng)上應(yīng)該有很多文章描述怎么做，但是很多方法比較麻煩，還好有工具已經(jīng)為我們解決了這個(gè)麻煩了。

// 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 屬性，應(yīng)該將這里的 dist 改為 .vuepress/dist
 "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>

總結(jié)

相比較 Hexo 而言 VuePress 上手更加容易，功能也更強(qiáng)大，例如在 VuePress 可以注冊(cè)自定義組件，而且 VuePress 中編寫 Vue 和平時(shí)一樣學(xué)習(xí)成本幾乎為零。所以如果您正在開源一款 Vue 相關(guān)的庫(kù)或是其他項(xiàng)目，您都可以使用 VuePress 作為您的文檔編輯工具。雖然并沒有完全將 VuePress 內(nèi)容講完，學(xué)完該篇文章相信你可以對(duì) VuePress 有個(gè)大概的了解，您至少可以快速搭建一個(gè)博客，如果您想對(duì) VuePress 有更多了解，請(qǐng)參考Vuepress 中文 API。

以上就是本文的全部?jī)?nèi)容，希望對(duì)大家的學(xué)習(xí)有所幫助，也希望大家多多支持腳本之家。

最新評(píng)論