先來一下演示效果。和vue的官方文檔幾乎是一致的，頁面內容都可自定義。
此教程部署后的效果預覽。
在你跟着教程搭建好項目之后，你會收獲：
- 快速搭建一個文檔/博客，后期只需要修改markdown內容和導航參數，即可一鍵打包生成頁面。
- 頁面具有非常好的加載性能和搜索引擎優化（SEO），其他的頁面則會只在用戶瀏覽到的時候才按需加載。
- 自動生成全局搜索、記錄上次修改時間等功能。
- 可嵌入vue組件或跳轉至其他頁面，可定制自己的樣式模板便於擴展。
- 一鍵免費部署到 github.pages，無需服務器即可擁有自己的在線文檔/博客。
vuepress是尤大開發的vue驅動的靜態網站生成器。項目整體以Markdown為中心結構，可以讓你用最少的配置完成文檔/博客寫作。但是，vuepress官方文檔真的對沒使用過類似於這種庫的人十分不友好，和vue的官方文檔的通俗易懂產生鮮明對比。里面的主題是什么東西？配置里面為什么沒有頁面和導航設置？首頁和其他頁面到底在哪？為什么主題還可以導出？看完vuepress官方文檔最大的感受就是一頭霧水。
事不宜遲！馬上開始我們的教程！
前置要求：
- 了解markdown文件格式：☆☆☆☆☆
- 安裝好npm/yarn的使用環境：☆☆☆☆☆
本教程難度：★☆☆☆☆
如何制作文檔結構？
首先先給大家明確很重要的兩個觀念：
- vuepress項目的文檔結構，都必須按照官方文檔的格式進行制作。比如說你想修改整體的主題顏色，你就必須修改styles文件夾下的palette.styl。你想在markdown中添加vue組件，vue組件必須放在components文件夾下，諸如此類。等到vuepress在打包的時候，它會遍歷特定的路徑和文件名稱，讀取內容生成頁面結構和樣式。
- 我們這里使用到的，都是官方的默認主題。主題的意思就是頁面的樣式和結構。你選擇了某一個主題，你的文檔內容結構就得根據當前主題進行設置。
接下來開始我們的制作。首先打開你的git客戶端，創建一個文件夾，並且進入文件夾。
mkdir testproject //創建文件夾，文件夾名字最好為小寫
cd testproject //進入文件夾 復制代碼然后使用npm全局安裝一下我們的vuepress。
npm install -g vuepress
復制代碼接下來初始化項目我們的項目信息，創建我們的pageckage.json文件
npm init -y
復制代碼創建完成后，進入我們的pageckage.json文件，在script中添加兩條命令
"scripts": { "dev": "vuepress dev docs", //用於實時預覽 "build": "vuepress build docs" //用於打包項目 }, 復制代碼接着我們需要創建vuepress項目的文件夾和文件，先創建好整體的架構再跟着教程了解里面的內容。不想一個個手動創建的也可以直接git clone一下我的項目，clone下來之后結構是一模一樣的。
//下面沒有文件類型后綴的都是文件夾
//部分內容並不是必須的，想自己定制的話可以參考官方文檔。這里是按照我的思路寫的。
├── docs
│ ├── .vuepress //存放核心內容的文件夾
│ │ ├── components //存放你需要添加的vue組件
│ │ ├── public //存放靜態文件，如圖片等
│ │ ├── styles //存放需要定制的樣式
│ │ │ └── palette.styl //配置頁面主題顏色的文件
│ │ └── config.js //設定頂部導航欄、側邊導航欄等項目配置的核心文件
│ ├── pages //存放markdown文件，用於設置其他頁面內容
│ ├── README.md //首頁展示用的markdown文件
├── deploy.sh //之后用於編寫上傳、發布腳本的文件
└── package.json //之前創建的Node.js項目描述文件
復制代碼
對整體項目結構有一定了解后，我們再了解將如何調整每個模塊。之后就可以對整個項目得心應手了。
官方的目錄結構較為豐富，可自行對照。
頁面的具體內容如何設置？
修改頁面整體設置
首先我們先設定網頁與瀏覽器標簽欄相關的一些設置，直接在我們的config.js文件增添下面的代碼。
module.exports = {
title: '裂泉首頁', // 顯示在左上角的網頁名稱以及首頁在瀏覽器標簽顯示的title名稱 description: '裂泉的前端記錄', // meta 中的描述文字，用於SEO // 注入到當前頁面的 HTML <head> 中的標簽 head: [ ['link', { rel: 'icon', href: '/egg.png' } //瀏覽器的標簽欄的網頁圖標，第一個'/'會遍歷public文件夾的文件 ], ], } 復制代碼修改完成后，在docs/.vuepress/public文件夾里面放置我們的logo圖片。
然后運行我們的npm run dev，打開http://localhost:8080/會得到如下效果。左上角的圖標和頁面名稱就設置好了：
設置首頁內容
接下來我們來設置首頁的內容，按照官網給的格式修改README.md文件，填寫如下內容
---
home: true heroImage: /egg.png heroText: 裂泉的前端記錄 tagline: 一點一滴都是進步 actionText: 馬上進入 → actionLink: /pages/folder1/test1.md features: - title: 簡潔至上 details: 以 Markdown 為中心的項目結構，以最少的配置幫助你專注於寫作。 - title: Vue驅動 details: 享受 Vue + webpack 的開發體驗，在 Markdown 中使用 Vue 組件，同時可以使用 Vue 來開發自定義主題。 - title: 高性能 details: VuePress 為每個頁面預渲染生成靜態的 HTML，同時在頁面被加載的時候，將作為 SPA 運行。 --- 復制代碼溫馨提示：heroImage的地址配置第一個'/'默認指向的是 docs/.vuepress/public，你需要在此文件夾放置你的首頁圖片。 actionLink地址配置第一個'/'默認指向的是 docs/，若未路徑文件不存在點擊進去會跳轉至404。文件路徑之后會詳細講解
上面的每個內容你都可以對照下面的圖片進行查看，都是一一對應的，此時再重新運行npm run dev，你的網頁應該如下圖所示。
修改頁面導航欄、側邊導航欄
導航欄修改和側邊欄修改還是在我們的config.js文件進行修改，在之前添加的moudule.exports里添加如下代碼：
module.exports = {
//...省略部分代碼
//下面涉及到的md文件和其他文件的路徑下一步再詳細解釋
themeConfig: {
logo: '/egg.png', //網頁頂端導航欄左上角的圖標 //頂部導航欄 nav: [ //格式一：直接跳轉，'/'為不添加路由，跳轉至首頁 { text: '首頁', link: '/' }, //格式二：添加下拉菜單，link指向的文件路徑 { text: '分類', //默認顯示 ariaLabel: '分類', //用於識別的label items: [ { text: '文章', link: '/pages/folder1/test1.md' }, //點擊標簽會跳轉至link的markdown文件生成的頁面 { text: '瑣碎', link: '/pages/folder2/test4.md' }, ] }, { text: '功能演示', link: '/pages/folder1/test3.md' }, //格式三：跳轉至外部網頁，需http/https前綴 { text: 'Github', link: 'https://github.com/dwanda' }, ], //側邊導航欄：會根據當前的文件路徑是否匹配側邊欄數據，自動顯示/隱藏 sidebar: { '/pages/folder1/':[ { title: '測試菜單1', // 一級菜單名稱 collapsable: false, // false為默認展開菜單, 默認值true是折疊, sidebarDepth: 1, // 設置側邊導航自動提取markdown文件標題的層級，默認1為h2層級 children: [ ['test1.md', '子菜單1'], //菜單名稱為'子菜單1'，跳轉至/pages/folder1/test1.md ['test3.md', '子菜單2'] ] }, { title: '測試菜單2', collapsable: false, children: [ ['test2.md', '子菜單1'] ] } ], //...可添加多個不同的側邊欄，不同頁面會根據路徑顯示不同的側邊欄 } } } 復制代碼此時我們的網頁首頁應該是這樣的。其他頁面暫時無法跳轉，因為此處點擊菜單時跳轉時，頁面對應的markdown文件為空，會跳轉至404頁面。而側邊欄則會自動匹配當前頁面路徑，若側邊欄數據存在當前頁面路徑，則顯示出來，路徑匹配不到則隱藏側邊欄，這也是為什么它可以不同頁面匹配不同的側邊欄的原因。
markdown及其他文件路徑解析
到這一步時，我們的導航欄、側邊欄、首頁都已經大概的概念了，但是你這時點擊我們的導航跳轉頁面，都會跳轉至會跳轉至404。我們的鏈接都是鏈接到markdown文件，在vuepress打包后會自動生成頁面。若鏈接對應的markdown文件不存在，則會跳轉404。若存在，則跳轉解析生成的頁面。
還有得明確一個概念，vuepress的文件尋址，不同類型的文件都已經預設好不同的默認路徑。比如說上一步的logo圖片引用的路徑，就是遍歷docs/.vuepress/public/egg.png尋找文件，我們只需要把圖片放在這個文件夾就可以了。markdown的文件就按我寫的放在docs/pages文件夾下，里面每個文件夾名字就是一個子路徑。如此類推。每個不同類型的文件必須放置在按照規定好的位置。
文件路徑的默認尋址方式
- 和圖標/圖片等靜態資源相關的，第一個 '/' 默認指向的是 docs/.vuepress/public/
- 側邊欄/導航欄鏈接的markdown文件，第一個 '/' 默認指向的是 docs/，我們這里是都放置在docs/pages里
- 嵌入在markdown中使用的Vue組件，放置在docs/.vuepress/components目錄中
此時你留意一下，我們在上一步設置頂端導航欄和側邊欄的時候，頂端的
分類-文章，側邊的
測試菜單1-子菜單1都共同指向
'/pages/folder1/test1.md'，當我們點擊其中一個鏈接時，跳轉的頁面都是一致的。都是會跳轉到
docs/pages/folder1/test1.md文件解析生成的頁面中。所有的導航欄都會根據當前頁面地址，判定當前導航的選中狀態。
根據之前設置的導航參數，我們需要在pages文件夾下創建以下的文件，並在每個markdwn文件中填寫一定的內容,便於測試效果。
## markdown示例內容，可以自己填寫別的。 #### 關於Vue下組件引入第三方外部外鏈Js幾種方式 https://blog.csdn.net/u010881899/article/details/80895661 #### nginx一鍵配置 https://nginxconfig.io/ #### lodash按需加載 https://www.jianshu.com/p/f03ff4f3a8b3 復制代碼當我們的markdown文件創建好之后，我們導航欄和側邊欄的跳轉鏈接也就有了對應的文件。我們再點擊進頂端導航欄的分類-文章，即可跳轉至如下頁面：
文檔結構大概梳理完之后，我們之后每次只需修改config.js文件中的導航欄和側邊欄，確保每個路徑對應的位置都存在有相對應的文件，我們就可以專注在markdown文檔的編輯中了。
如何一鍵部署至github page？
創建遠程倉庫
github.pages官方的意圖是為了給github項目提供一個自定義的界面，讓用戶可以有更豐富的頁面來介紹自己的項目。每個倉庫只能擁有一個自己的主站點，並在此基礎上進行擴展。因為沒有數據庫的關系，所以只能夠搭建靜態網頁。其實就相當於一個免費的服務器可以讓你部署自己的頁面了。
創建和使用的步驟也很簡單。首先登陸你的github賬號，將鼠標移至右上角的加號，點擊new repository，然后在Repository name填寫'你的用戶名'+.github.io，例如：dwanda.github.io。之后什么都不用設置，直接點下面的Create repository，就完成創建倉庫的步驟了。
倉庫名字必須為你的用戶名+.github.io，否則需要另外設置。
配置本地推送至遠程倉庫的權限
這里參考的是如何將本地項目上傳到Github這篇文章的配置過程。使用的是gitbash，若windows沒有的話建議裝一個。mac的話就參考一下這篇文章的配置過程。
進入git-bash界面然后：
第一步，輸入
git config --global --list
復制代碼驗證郵箱與GitHub當前創建倉庫的賬號和名字是否一致。 若不一致的話，通過下面命令進行修改。
git config --global user.name 你的用戶名， //設置全局用戶名。
git config --global user.email 你的登陸郵箱， //設置郵箱。
復制代碼第二步，運行下面的命令，在本地電腦生產密鑰
ssh-keygen -t rsa -C 你的登陸郵箱
復制代碼第三步，命令執行成功后會在你的電腦的C:\Users\你的用戶名\.ssh的文件夾中，生成下面的文件。
我們用記事本打開
id_rsa.pub文件，復制文本中的內容
第四步，打開我們的github頁面，點擊右上角的頭像，點擊下拉菜單的setting，跳轉頁面后點擊側邊欄的SSH and GPG keys，點擊New SHH key進入我們如下界面
title隨便填就可以了，將上一步復制的內容粘貼至key中，保存。
第五步，測試是否連接上github
ssh -T git@github.com
復制代碼如果通了的話會顯示如下界面:
出現下面的界面的時候，輸入yes按回車，再測試一遍就通過了。
到這里我們的權限就已經配置好了。
使用腳本編寫打包、上傳命令
接着按照官方的部署教程，我們需要修改一開始創建的deploy.sh文件。該文件的作用是用於批量執行我們的打包、上傳至倉庫等命令。而.sh格式是腳本文件。
deploy.sh文件內容：
# 確保腳本拋出遇到的錯誤 set -e # 打包生成靜態文件 npm run build # 進入打包好的文件夾 cd docs/.vuepress/dist # 創建git的本地倉庫，提交修改 git init git add -A git commit -m 'deploy' # 覆蓋式地將本地倉庫發布至github，因為發布不需要保留歷史記錄 # 格式為：git push -f git@github.com:'用戶名'/'倉庫名'.git master git push -f git@github.com:dwanda/dwanda.github.io.git master cd - 復制代碼然后修改我們的package.json，在里面添加一條執行我們腳本文件的命令
"scripts": { ...... "deploy": "bash deploy.sh" }, //bash就是用來執行文件的命令，如果報錯顯示沒有此命令請安裝git-bash使用，或改成"start deploy.sh" 復制代碼之后我們每次執行的時候，只需要運行
npm run deploy
復制代碼就可完成打包、上傳操作，github會為我們自動更新頁面代理。一般推送成功后需要等待一兩分鍾，你再打開https://你的用戶名.github.io，就可以看到你的文檔/博客頁面啦。在完成整個項目的結構調整后，只需編輯一丟丟地方，即可實現編輯文檔+維護，是不是很方便呢！
其他問題：
熱更新問題
由於項目結構沒有熱更新，所以每次調整config.js之后，都需要重新npm run dev一次。更新已存在的markdown文件的時候會實時熱更新。
修改主題顏色
只需要在我們的**'.vuepress/styles/palette.styl'**文件中添加一下代碼，再修改它的顏色進行保存，就會自動改變。
// 默認值
$accentColor = #3eaf7c //主題顏色 $textColor = #2c3e50 $borderColor = #eaecef $codeBgColor = #282c34 $badgeTipColor = #42b983 $badgeWarningColor = darken(#ffe564, 35%) $badgeErrorColor = #DA5961 復制代碼其他更多的顏色可以參考官網的默認預設。
在markdown中嵌入vue組件
首先先把vue組件編輯好，直接放在我們之前創建的docs/.vuepress/components文件夾中，如下圖所示：
你只需要在markdown文件中，直接按下面的方法使用組件。無需其他引入即可加載vue組件。
<ClientOnly>
<HomeLayout/> //你的組件名字
</ClientOnly>
復制代碼倉庫名字無法按照格式
如果倉庫名字不能使用用戶名+github.io，或者需要放置於某個項目的子目錄中。需要參考官網修改我們的config.js設置根路徑，並參考此處修改deploy.sh文件的發布到github的路徑。之后去倉庫中的setting的github Pages將你的source設置成master，刷新，你就能在setting的github Pages看到頁面部署后的地址了。圖片相關的路徑也需要更改，具體可以參考評論區的解決方案。建議新手就按我上面來好了，少點麻煩。
vue組件加載延遲問題
因為vue的加載和markdown解析出來的頁面組件會產生加載時間不一致的問題，視覺上會造成遲鈍。
- 建議只使用純markdown編寫頁面
- 或在markdown中只嵌入vue組件，不添加其他markdown語句。
markdown內容的其他擴展
- 添加本地圖片資源
- markdown的樣式其他擴展規則，包括代碼行號、不同格式代碼的高亮、自定義容器等。
- markdown的鏈接的默認跳轉規則，默認都是跳轉至網站內部的其他頁面，如需跳轉至外部頁面記得加上
http/https前綴。
官網一些其他功能
文章在這里就結束啦，以下是看了這篇文章的兩個路人：
作者：裂泉
鏈接：https://juejin.im/post/5dce1e0e5188254eda3936c5
來源：掘金
著作權歸作者所有。商業轉載請聯系作者獲得授權，非商業轉載請注明出處。