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.jsconfig.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：
{{}} 啦 {{}}所以我們的代碼塊要以這種形式書寫：
//```js {{}} 啦 {{}} // 注釋需要打開 這樣vuepress會把這里面包裹的當成代碼塊而不是js //```并且這樣也會讓我們的代碼高亮顯示(下圖第一個沒有高亮，第二個有高亮)，閱讀體驗更好：
自定義容器了解一下：
更改標題：
::: 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' > CNAMEgit init git add -A git commit -m 'deploy'# 如果發布到 https://<USERNAME>.github.io USERNAME=你的用戶名 # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master# 如果發布到 https://<USERNAME>.github.io/<REPO> REPO=github上的項目 # git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pagescd -設置package.json：
{
"scripts": {
}
}
部署：
然后你每次可以運行下面的命令行，來把最新更改推到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組件等，這些功能我也還在摸索，所以大家一定要去看文檔!
結語
上面已經寫得盡可能詳細了，我遇到的坑都寫上去了。搭建起來確實很簡單，心動不如行動，隨手花一兩個小時搭建一下又不吃虧，何樂而不為？
希望看完的朋友可以點個喜歡/關注，您的支持是對我最大的鼓勵。
個人blog and 前端積累文檔，如需轉載，請放上原文鏈接并署名。碼字不易，感謝支持！
如果喜歡本文的話，歡迎掃描關注我的訂閱號，最新文章，面試題等都將第一時間發布在訂閱號上。
以上2018.9.9
總結
以上是生活随笔為你收集整理的VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： ASP.NET 2.2 Preview
- 下一篇： 少侠请重新来过 - Vue学习笔记(二)