Vuepress 搭建靜態博客全攻略

想在兩個小時以內搭建出來一個帶有評論系統和谷歌數據分析的靜態博客，同時完成靜態博客的自動構建和部署嗎🚀？

這篇文章對每一個步驟都作了詳細的記錄，還把每一個步驟中踩過的坑梳理了出來，，絕對能夠給你提供不少幫助～

後續我還會加上「複製博客文章內容加上版本信息」、「全文檢索」等功能，敬請期待💪

博客的最終效果能夠看這裏

Vuepress 搭建靜態博客

能夠參照 Vuepress 的官方文檔 一步一步來就行了，我這裏就簡單說下步驟：

1. 安裝 Vuepress

你能夠全局安裝：

# 可使用 npm 來全局安裝
npm i -g Vuepress

# 也可使用 yarn 來全局安裝
yarn global add Vuepress
複製代碼

也能夠安裝在你靜態博客項目的開發依賴裏面:

yarn add --dev Vuepress

# 或者
npm i -D Vuepress
複製代碼

2. 初始化博客項目

# 可使用 npm 來初始化項目
npm init

# 也可使用 yarn 來初始化項目
yarn init
複製代碼

而後在項目的根目錄下新建一個 docs 文件夾，之後咱們寫的 markdown 文件都會放在 docs 文件夾下。

咱們先隨便初始化一個文件來看看效果：

echo '# Hello VuePress!' > docs/README.md
複製代碼

執行命令 vuepress dev docs

能夠看到啓動了一個頁面：

爲了後續運行方便，咱們能夠把這些命令寫在項目的 package.json 文件裏面的 scripts：

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
 }
複製代碼

3. 進一步的配置

目前咱們只寫了一個 markdown 文檔，因此只有一個頁面，後續咱們的博客會陸續加入不少內容，確定須要作目錄分級，配置導航欄，能夠看文檔裏的這部分

4. 部署

靜態博客搭好了，咱們就能夠把它部署到服務器上正式給別人訪問了，你可使用 GitHub Pages（GitHub 的靜態頁面託管服務 ）來託管本身的靜態博客。 可使用 gh-pages 來將打包好的靜態博客快速部署到 GitHub Pages 上。

一樣的，咱們能夠將部署的命令加入到 package.json 文件裏面的 scripts，如今，咱們的 scripts 就是這樣的：

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs",
    "deploy": "npm run build && gh-pages -d docs/.vuepress/dist"
  },
 }
複製代碼

您也可使用其餘第三方靜態頁面託管服務（如 Netlify、Coding Pages、Gitlab Pages 等），這篇文章裏面介紹了不少免費的靜態頁面託管服務。

到這一步，你的博客已經能夠順利地運行、構建和部署了，直接執行 npm run deploy 就能夠將您的博客部署到 GitHub Pages 上去，若是您還想讓你的博客書寫和使用的體驗更好，能夠接着往下看。

GitHub Actions 自動構建/部署

你們有注意到 GitHub 悄悄上線了一個 Actions 功能嗎？還不瞭解的同窗能夠看這篇文章，寫的很是全面。

GitHub Actions 是什麼呢？GitHub 官方號稱 Actions 可讓你的**工做流自動化**：GitHub 監聽某個事件（多是某個分支的提交），而後觸發你預約義的工做流，讓你們在GitHub服務器上直接測試代碼、部署代碼。因此，咱們能夠利用這裏特性來作 CI/CD，開發者只要寫一下 workflow 腳本就能夠了，不用費心思去想要用哪一個第三方的 CI/CD 服務。

actions 其實就是由一些腳本組成，因此它們是能夠複用的，GitHub 作了一個官方市場，能夠搜索到他人提交的 actions。另外，還有一個 awesome actions 的倉庫，也能夠找到很多 action。這樣一來，你甚至都不用本身寫具體的腳本，直接引用別人的腳本就行啦。

話很少說，趕忙用起來！

寫 workflow 腳本

首先咱們須要到項目倉庫的頁面上進入 Actions 這個 tab, 選擇 Node 環境進入腳本的編輯頁面

這裏我直接使用了 peaceiris 的 actions-gh-pages，這個 action 能夠幫你把打包好的靜態文件部署到 GitHub Pages 上去。

最終個人 workflow 腳本以下：

這裏有個人 腳本源文件，能夠參考一下。

更詳細的語法能夠去看 GitHub Actions 的官方文檔

注意⚠️

由於我用的 action 是第三方的，因此 action 可能會常常更改，若是你是過了一段時間纔看到這篇文章，peaceiris 的 actions-gh-pages 極可能已經發生了更新，因此腳本的內容建議直接參照它的官方文檔來寫。

設置 workflow 的環境變量

上面的腳本里面第21行的環境變量是怎麼回事呢？

由於咱們須要 GitHub Actions 把構建成果發到 GitHub 倉庫，所以須要 GitHub 密鑰，至關因而給 GitHub actions 受權。

首先運行下面的命令生成一對密鑰：

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
# gh-pages.pub (public key)
# gh-pages (private key)
複製代碼

而後：

1. 在博客項目的倉庫的 Settings 欄下，找到 Deploy keys這一項，把你的公鑰加進去，注意勾選Allow write access
2. 一樣在博客項目的倉庫的 Settings 欄下，找到 Secrets這一項，把你的私鑰加進去

   

注意事項

1. 把 Vuepress 做爲你的開發依賴加入到項目的 package.json 文件裏面進行管理。（不然在 GitHub 的 docker 容器裏打包的時候會找不到 Vuepress 這個命令）
2. 使用 npm 而不是 yarn 來管理依賴包。（由於 npm 是 node 環境自帶的包管理工具，無需額外安裝，另外， peaceiris 的 actions-gh-pages 也是使用 npm 做爲包管理工具的）
3. 使用 npm ci 來安裝依賴包，而不是 npm install

npm ci 和 npm i 的區別能夠看 medium 上的這篇文章 瞭解一下。

簡單來講就是：不像npm install，npm ci永遠不會修改您的package-lock.json，它的使用依賴於 package-lock.json文件。因此若是使用npm ci，您將得到可靠的版本。一般這個命令會在 Jenkins或GitLab CI之類的持續集成工具中使用。

好了，這樣每次你的項目 master 分支一旦有新的提交，就會自動觸發這個 workflow，就能夠自動完成靜態博客的構建和部署了～

也就是說，咱們能夠直接利用 GitHub 的 markdown 編輯器，直接新建一個文檔進行協做，而後提交到 master 分支就好了，徹底不用再次去作 git 提交以及本地的構建和部署，簡直太方便了 :rocket:

添加評論系統

搭建博客的目的確定是爲了能和更多技術同好交流，因此評論系統是不可或缺的一個功能。

咱們可使用 gitalk 這個開源的評論插件來作博客的評論系統，它是基於 GitHub Issue 來開發的，能夠直接使用 GitHub 帳號登陸，這對程序員來講真的是至關友好了👬

註冊 GitHub OAuth Application

首先要申請一個 GitHub OAuth Application。能夠點擊這裏申請.

注意:

Authorization callback URL 必定要填寫當前使用插件頁面的域名。

註冊成功後你會獲得一個 Client ID 和 Client Secret，這兩個數據咱們下一步要用到。

建立評論組件

咱們回到工程，在 docs/.vuepress 下新建一個文件夾 components，再在 components 文件夾下建一個 comment 文件夾，而後新建文件 comment.vue，並複製下面的代碼。

<template>
  <div class="gitalk-container">
    <div id="gitalk-container"></div>
  </div>
</template>
<script> export default { name: 'comment', data() { return {}; }, mounted() { let body = document.querySelector('.gitalk-container'); let script = document.createElement('script'); script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js'; body.appendChild(script); script.onload = () => { const commentConfig = { clientID: 'YOUR_CLINENT_ID', clientSecret: 'YOUR_CLINENT_SECRET', repo: '此倉庫的名稱', owner: '你的 GitHub 用戶名，注意是用戶名！！！', // 這裏接受一個數組，能夠添加多個管理員 admin: ['你的 GitHub 用戶名'], // id 用於當前頁面的惟一標識，通常來說 pathname 足夠了， // 可是若是你的 pathname 超過 50 個字符，GitHub 將不會成功建立 issue，此狀況能夠考慮給每一個頁面生成 hash 值的方法. id: location.pathname, distractionFreeMode: false, }; const gitalk = new Gitalk(commentConfig); gitalk.render('gitalk-container'); }; }, }; </script>
複製代碼

注意:

id 不能超過50個字符，不然後續評論組件初始化的時候會發生Error：validation failed 的報錯。

你可使用較短的字符來做爲 id，例如我本身是使用 document.title.replace(/\s\|\s去衝浪鴨|《|》/g, "")來做爲 id 的，即便用個人文章標題做爲 id。

配置組件

在工程根目錄下新建一個文件夾 builds，並在裏面新建三個文件，分別是 findMarkdown.js, addComponents.js 和 delComponents.js。

findMarkdown.js 文件讀取你全部的 Markdown 文件的內容。

// findMarkdown.js
const fs = require('fs')

function findMarkdown(dir, callback) {
  fs.readdir(dir, function (err, files) {
    if (err) throw err

    files.forEach((fileName) => {
      let innerDir = `${dir}/${fileName}`

      if (fileName.indexOf('.') !== 0) {
        fs.stat(innerDir, function (err, stat) {

          if (stat.isDirectory()) {
            findMarkdown(innerDir, callback)
          } else {
            // 跳過readme 文件，固然你也能夠自行修改
            if (/\.md$/.test(fileName) && !/README/.test(fileName))
              callback(innerDir);
          }
        })
      }

    })
  })
}

module.exports = findMarkdown
複製代碼

addMarkdown.js 文件將 comment 組件註冊到每一個 Markdown 文件的最後。

// addMarkdown.js
const fs = require('fs')
const findMarkdown = require('./findMarkdown')
const rootDir = './docs'

findMarkdown(rootDir, writeComponents)

function writeComponents(dir) {
  if (!/README/.test(dir)) {
    fs.appendFile(dir, `\n \n <comment-comment/> \n `, (err) => {
      if (err) throw err
      console.log(`add components to ${dir}`)
    })
  }
}
複製代碼

delMarkdown.js 文件在編譯後執行，目的是將每一個 Markdown 文件的 comment 組件移除，由於咱們只想讓 comment 組件打包到編譯後的文件中，而非工程文件。

// delMarkdown.js
const fs = require('fs')
const findMarkdown = require('./findMarkdown')
const rootDir = './docs'

findMarkdown(rootDir, delComponents)

function delComponents(dir) {
  fs.readFile(dir, 'utf-8', (err, content) => {
    if (err) throw err

    fs.writeFile(dir, content.replace(/\n \n <comment-comment\/> \n /g, ''), (err) => {
      if (err) throw err
      console.log(`del components from ${dir}`)
    })
  })
}
複製代碼

修改構建腳本

修改 build 的腳本：

{
  "build": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js"
}
複製代碼

好了，這樣你的博客就有一個評論系統了，效果以下：

每次有人在一篇評論數爲0的文章下面評論，就會自動以當前文章爲標題，當前文章的網址爲內容生成一條 GitHub Issue，評論就會被關聯到這條 GitHub Issue 上。

配置全文搜索

待補充...

配置 Google Analytics

博客搭建好了，也有人訪問了，那咱們要怎麼統計用戶的訪問狀況呢？可使用谷歌出品的 Google Analytics （GA）。

Google Analytics （GA）是一個對用戶活動進行追蹤的工具，利用 GA 咱們能夠收集到博客當前有多少實時活躍用戶，博客的總訪問量，以及分析用戶的一些訪問行爲，便於咱們對博客網站作一些優化，並且它仍是免費的！趕快用起來！

下載 google-analytics 插件

Vuepress 官方已經爲咱們準備好了 google-analytics 插件。

yarn add -D @vuepress/plugin-google-analytics
# OR npm install -D @vuepress/plugin-google-analytics
複製代碼

安裝完在 config 配置文件裏面配置一下 plugins

module.exports = {
  plugins: [
    [
      '@vuepress/google-analytics',
      {
        'ga': '' // UA-00000000-0
      }
    ]
  ]
}
複製代碼

註冊 GA，獲取追蹤 ID

上面那個 ga ID從哪裏獲取呢？彆着急，咱們須要到 Google Analytics 的官網上去註冊一下咱們的博客應用：

進去後選擇 web app:

把獲取到的跟蹤ID 填到上面👆的ga這一項裏面就行了。

給 Vuepress 博客作 SEO 優化

待補充...

複製文字時顯示版權信息

待補充...