1小時搞定vuepress快速製做vue文檔/博客+免費部署預覽

時間 2019-11-21

標籤小時搞定 vuepress 快速製做 vue 文檔博客免費部署預覽简体版

原文原文鏈接

先來一下演示效果。和vue的官方文檔幾乎是一致的，頁面內容均可自定義。
此教程部署後的效果預覽。html

在你跟着教程搭建好項目以後，你會收穫：前端

快速搭建一個文檔/博客，後期只須要修改markdown內容和導航參數，便可一鍵打包生成頁面。
頁面具備很是好的加載性能和搜索引擎優化（SEO），其餘的頁面則會只在用戶瀏覽到的時候才按需加載。
自動生成全局搜索、記錄上次修改時間等功能。
可嵌入vue組件或跳轉至其餘頁面，可定製本身的樣式模板便於擴展。
一鍵免費部署到 github.pages，無需服務器便可擁有本身的在線文檔/博客。

vuepress是尤大開發的vue驅動的靜態網站生成器。項目總體以Markdown爲中心結構，可讓你用最少的配置完成文檔/博客寫做。可是，vuepress官方文檔真的對沒使用過相似於這種庫的人十分不友好，和vue的官方文檔的通俗易懂產生鮮明對比。裏面的主題是什麼東西？配置裏面爲何沒有頁面和導航設置？首頁和其餘頁面到底在哪？爲何主題還能夠導出？看完vuepress官方文檔最大的感覺就是一頭霧水。vue

事不宜遲！立刻開始咱們的教程！

前置要求：webpack

瞭解markdown文件格式：☆☆☆☆☆
安裝好npm/yarn的使用環境：☆☆☆☆☆

本教程難度：★☆☆☆☆nginx

如何製做文檔結構？

首先先給你們明確很重要的兩個觀念：git

vuepress項目的文檔結構，都必須按照官方文檔的格式進行製做。好比說你想修改總體的主題顏色，你就必須修改styles文件夾下的palette.styl。你想在markdown中添加vue組件，vue組件必須放在components文件夾下，諸如此類。等到vuepress在打包的時候，它會遍歷特定的路徑和文件名稱，讀取內容生成頁面結構和樣式。
咱們這裏使用到的，都是官方的默認主題。主題的意思就是頁面的樣式和結構。你選擇了某一個主題，你的文檔內容結構就得根據當前主題進行設置。

接下來開始咱們的製做。首先打開你的git客戶端，建立一個文件夾，而且進入文件夾。github

mkdir testproject   //建立文件夾，文件夾名字最好爲小寫
cd testproject      //進入文件夾
複製代碼

而後使用npm全局安裝一下咱們的vuepress。web

npm install -g vuepress
複製代碼

接下來初始化項目咱們的項目信息，建立咱們的pageckage.json文件數據庫

npm init -y 
複製代碼

建立完成後，進入咱們的pageckage.json文件，在script中添加兩條命令npm

"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看到頁面部署後的地址了。圖片相關的路徑也須要更改，具體能夠參考評論區的解決方案。建議新手就按我上面來好了，少點麻煩。