一篇帶你用 VuePress + Github Pages 搭建部落格

前言

最近完成了 TypeScript 最新官方文件 Hanbook 的翻譯，一共十四篇，堪稱國內的最好 TypeScript4 入門教程之一。為了方便大家閱讀，我用 VuePress + Github Pages 搭建了部落格，部落格效果如下：

部落格地址如下：

• Github https://mqyqingfeng.github.io/learn-typescript/
• Gitee http://mqyqingfeng.gitee.io/learn-typescript/

0. VuePress

VuePress 自然不用多說，基於 Vue 的靜態網站生成器，風格簡約，配置也比較簡單。之所以不使用 VitePress，是因為想使用現有的主題， 而 VitePress 不相容當前 VuePress 的生態系統，至於為什麼不選擇 VuePress@next，考慮到還處於 Beta 階段，等穩定後再開始遷移。

1. 本地搭建

快速開始同 VuePress 官網：

1. 建立並進入一個新目錄

// 檔名自定義
mkdir vuepress-starter && cd vuepress-starter

2. 使用你喜歡的包管理器進行初始化

yarn init # npm init

3. 將 VuePress 安裝為本地依賴

yarn add -D vuepress # npm install -D vuepress

4. 建立你的第一篇文件，VuePress 會以 docs 為文件根目錄，所以這個 README.md 相當於主頁：

mkdir docs && echo '# Hello VuePress' > docs/README.md

5. 在 package.json 中新增一些 scripts

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

6. 在本地啟動伺服器

yarn docs:dev # npm run docs:dev

VuePress 會在 http://localhost:8080 (opens new window) 啟動一個熱過載的開發伺服器。

2. 基礎配置

在文件目錄下建立一個 .vuepress 目錄，所有 VuePress 相關的檔案都會被放在這裡。此時你的專案結構可能是這樣：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

在 .vuepress 資料夾下新增 config.js，配置網站的標題和描述，方便 SEO：

module.exports = {
  title: 'TypeScript4 文件',
  description: 'TypeScript4 最新官方文件翻譯'
}

此時介面類似於：

3. 新增導航欄

我們現在在頁首的右上角新增導航欄，修改 config.js:

module.exports = {
    title: '...',
    description: '...',
    themeConfig: {
        nav: [
            { text: '首頁', link: '/' },
            { 
                text: '冴羽的 JavaScript 部落格', 
                items: [
                    { text: 'Github', link: 'https://github.com/mqyqingfeng' },
                    { text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts' }
                ]
            }
        ]
    }
}

效果如下：

更多的配置參考 VuePress 導航欄。

4. 新增側邊欄

現在我們新增一些 md 文件，目前文件的目錄如下：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
|  └─ handbook
|        └─ ConditionalTypes.md
|        └─ Generics.md
└─ package.json

我們在 config.js 配置如下：

module.exports = {
    themeConfig: {
        nav: [...],
        sidebar: [
            {
                title: '歡迎學習',
                path: '/',
                collapsable: false, // 不折疊
                children: [
                    { title: "學前必讀", path: "/" }
                ]
            },
            {
              title: "基礎學習",
              path: '/handbook/ConditionalTypes',
              collapsable: false, // 不折疊
              children: [
                { title: "條件型別", path: "/handbook/ConditionalTypes" },
                { title: "泛型", path: "/handbook/Generics" }
              ],
            }
          ]
    }
}

對應的效果如下：

5. 更換主題

現在基本的目錄和導航功能已經實現，但如果我還想要載入 loading、切換動畫、模式切換（暗黑模式）、返回頂部、評論等功能呢，為了簡化開發成本，我們可以直接使用主題，這裡使用的主題是 vuepress-theme-rec：

現在我們安裝 vuepress-theme-reco：

npm install vuepress-theme-reco --save-dev
# or
yarn add vuepress-theme-reco

然後在 config.js 裡引用該主題：

module.exports = {
  // ...
  theme: 'reco'
  // ...
}  

重新整理一下頁面，我們會發現一些細節的改變，比如載入時的 loading 動畫、以及支援切換暗黑模式：

6. 新增文章資訊

但我們也會發現，像條件型別這一篇文章，條件型別（Conditional Types） 竟然出現了兩遍，這是因為這個主題自動提取了第一個大標題作為本文的標題，我們可以在每篇文章的 md 檔案中新增一些資訊修改：

---
title: 條件型別
author: 冴羽
date: '2021-12-12'
---

此時文章的效果如下：

但如果你不想要標題、作者、時間這些資訊呢，我們可以在樣式裡隱藏，這個稍後會講到。

7. 設定語言

注意，上圖的文章時間，我們寫入的格式為 2021-12-12 ，但是顯示的是 12/12/2021，這是因為 VuePress 預設的 lang 為 en-US，我們修改一下 config.js：

module.exports = {
  // ...
  locales: {
    '/': {
      lang: 'zh-CN'
    }
  },
  // ...
}  

可以發現時間換了一種展示方式：

8. 開啟目錄結構

在原本的主題裡，我們發現每篇文章的目錄結構出現在左側：

而 vuepress-theme-reco 將原有的側邊欄的中的多級標題移出，生成子側邊欄，放在了頁面的右側，如果你要全域性開啟，可在頁面 config.js 裡設定開啟：

module.exports = {
  //...
  themeConfig: {
    subSidebar: 'auto'
  }
  //...
}

此時效果如下：

9. 修改主題顏色

VuePress 基於 Vue，所以主題色用的是 Vue 的綠色，然而 TypeScript 的官方色則是藍色，那如何修改 VuePress 的主題色呢？

你可以建立一個 .vuepress/styles/palette.styl 檔案，檔案程式碼如下：

$accentColor = #3178c6

此時可以發現主題顏色變了：

更多的顏色修改參考 VuePress 的 palette.styl。

10. 自定義修改樣式

如果你想自定義修改一些 DOM 元素的樣式呢？就比如在暗黑模式下：

我們發現用作強調的文字顏色比較暗淡，在暗黑模式下看不清楚，我想改下這個文字的顏色和背景色呢？

而 VuePress 提供了一種新增額外樣式的簡便方法。你可以建立一個 .vuepress/styles/index.styl 檔案。這是一個 Stylus 檔案，但你也可以使用正常的 CSS 語法。

我們在 .vupress 資料夾下建立這個目錄，然後建立 index.styl 檔案，程式碼如下：

// 通過檢查，檢視元素樣式宣告
.dark .content__default code {
    background-color: rgba(58,58,92,0.7);
    color: #fff;
}

此時文字就清晰了很多：

那之前我們提到的隱藏每篇文章的標題、作者、時間呢，其實也是類似的方式：

.page .page-title {
   display: none;
}

最後的效果如下：

11. 部署

我們的部落格就算是正式的做好了，接下來我們部署到免費的 Github Pages 上。我們在 Github 上新建一個倉庫，這裡我取得倉庫名為：learn-typescript。

對應，我們需要在 config.js 新增一個 base 路徑配置：

module.exports = {
      // 路徑名為 "/<REPO>/"
    base: '/learn-typescript/',
      //...
}

最終的 config.js 檔案內容為：

module.exports = {
    title: 'TypeScript4 文件',
    description: 'TypeScript4 最新官方文件翻譯',
    base: '/learn-typescript/',
    theme: 'reco',
    locales: {
        '/': {
          lang: 'zh-CN'
        }
    },
    themeConfig: {
        // lastUpdated: '上次更新',
        subSidebar: 'auto',
        nav: [
            { text: '首頁', link: '/' },
            { 
                text: '冴羽的 JavaScript 部落格', 
                items: [
                    { text: 'Github', link: 'https://github.com/mqyqingfeng' },
                    { text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts' }
                ]
            }
        ],
        sidebar: [
            {
                title: '歡迎學習',
                path: '/',
                collapsable: false,
                children: [
                    { title: "學前必讀", path: "/" }
                ]
            },
            {
              title: "基礎學習",
              path: '/handbook/ConditionalTypes',
              collapsable: false,
              children: [
                { title: "條件型別", path: "/handbook/ConditionalTypes" },
                { title: "泛型", path: "/handbook/Generics" }
              ],
            }
          ]
    }
}

然後我們在專案 vuepress-starter 目錄下建立一個指令碼檔案：deploy.sh，注意修改一下對應的使用者名稱和倉庫名：

#!/usr/bin/env sh

# 確保指令碼丟擲遇到的錯誤
set -e

# 生成靜態檔案
npm run docs:build

# 進入生成的資料夾
cd docs/.vuepress/dist

git init
git add -A
git commit -m 'deploy'

# 如果釋出到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:mqyqingfeng/learn-typescript.git master:gh-pages

cd -

然後命令列切換到 vuepress-starter 目錄下，執行 sh deploy.sh，就會開始構建，然後提交到遠端倉庫，注意這裡提交到了 gh-pages 分支，我們檢視下對應倉庫分支的程式碼：

我們可以在倉庫的 Settings -> Pages 中看到最後的地址：

像我最後生成的地址就是 https://mqyqingfeng.github.io/learn-typescript/

至此，我們完成了 VuePress 和 Github Pages 的部署。

系列文章

系列文章目錄地址：https://github.com/mqyqingfeng/Blog

微信：「mqyqingfeng」，加我進冴羽唯一的讀者群。

如果有錯誤或者不嚴謹的地方，請務必給予指正，十分感謝。如果喜歡或者 有所啟發，歡迎 star，對作者也是一種鼓勵。