如何用VuePress + Github Pages搭建一個博客

如何用VuePress + Github Pages搭建一個博客，針對這個問題，這篇文章詳細介紹了相對應的分析和解答，希望可以幫助更多想解決這個問題的小伙伴找到更簡單易行的方法。

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 導航欄：

https://vuepress.vuejs.org/zh/theme/default-theme-config.html#%E5%AF%BC%E8%88%AA%E6%A0%8F

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（https://vuepress-theme-reco.recoluan.com/）：

現在我們安裝 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 中看到最后的地址：

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

關于如何用VuePress + Github Pages搭建一個博客問題的解答就分享到這里了，希望以上內容可以對大家有一定的幫助，如果你還有很多疑惑沒有解開，可以關注億速云行業資訊頻道了解更多相關知識。