VuePress + GitHub Pages 搭建個人博客

前言

我相信每一個程序員入門時，都經歷過搭建一個個人博客這樣的階段。確實這是一個好的練手項目，而搭建博客難度也可高可低，取決於個人目標。本文提供了一個選擇，可基於 GitHub 的 GitHub Pages 功能 和 Vuepress 框架快速地搭建免費的markdown博客：

• 對於文檔編寫者來說，能更專注於寫文章
• 對於文檔開發者來說，一切皆Vue組件，能方便地自定義主題

Vuepress官網：https://vuepress.vuejs.org/zh/

基本工具

1. node.js以及npm包管理工具： https://nodejs.org/en/
2. git工具：https://git-scm.com/downloads

構建基本項目結構

1. 新建一個名爲 blog-demo 的文件夾，命令行進入到該文件夾目錄，輸入命令：

# 按默認配置初始化一個項目，此時會在當前目錄下生成 package.json 文件
npm init -y

2. 將 VuePress 作爲一個本地依賴安裝

npm install -D vuepress

3. 在 package.json 裏的 scripts 中添加如下代碼，不需要修改其它代碼

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

4. 在項目根目錄下，新建 docs 文件夾

mkdir docs

5. 新建一個 markdown 文件

echo '# Hello VuePress!' > docs/README.md

6. 輸入命令啓動項目，在瀏覽器中訪問 http://localhost:8080/ 即可預覽效果

npm run docs:dev

基本配置

現在我們已經構建出了最基本的項目結構，並且可以在瀏覽器中預覽到 docs 目錄下的 README.md 文件的效果，該文件即是我們網站的首頁，如圖所示：

然而如果沒有任何配置，用戶將無法在網站上自由導航。因此，爲了更好地自定義我們的網站，我們接着在 docs 目錄下新建 .vuepress 文件夾，執行命令如下：

# 新建 .vuepress 文件夾
mkdir docs\.vuepress

接着在 .vuepress 文件夾下新建 config.js 文件,這裏的 config.js 便是一個 Vuepress 網站必要的配置文件，在其中添加如下代碼：

module.exports = {
  base: '/blog-demo/',
  title: 'blog-demo',
  description: 'Vuepress blog demo'
}

其中配置項的含義爲：

• base：站點的基礎路徑，它的值應當總是以斜槓開始，並以斜槓結束。這裏設置爲 /blog-demo/ ，我們再次在本地運行項目，訪問路徑就需要變更爲 http://localhost:8080/blog-demo/
• title：網站的標題
• description：網站的描述

默認主題配置

Vuepress 提供了一個默認主題，讓我們不必自己去從零實現複雜的 markdown 文件渲染、目錄結構等，直接按照規則去使用它即可。如果你想自定義自己的主題，請查看官方文檔：Vuepress-開發主題。

首頁

默認主題提供了一個首頁的佈局，想要使用它，需要在你的根級 README.md 以格式 YAML front matter 指定 home: true。因此，將我們最初創建的 README.md 修改一下：

---
home: true
heroImage: /vue-logo.png
heroText: blog-demo
tagline: 博客示例
actionText: 快速上手 →
actionLink: /
features:
- title: 簡潔至上
  details: 以 Markdown 爲中心的項目結構，以最少的配置幫助你專注於寫作。
- title: Vue驅動
  details: 享受 Vue + webpack 的開發體驗，在 Markdown 中使用 Vue 組件，同時可以使用 Vue 來開發自定義主題。
- title: 高性能
  details: VuePress 爲每個頁面預渲染生成靜態的 HTML，同時在頁面被加載的時候，將作爲 SPA 運行。
---

• heroImage: 首頁圖片，圖片放置在 .vupress/public 文件夾下，若沒有該文件夾則自己創建一個，保存一張你想要的首頁圖片，並在此處引用。
• 其它參數請參考官方文檔：Vuepress-默認主題首頁

導航欄

導航欄可能包含你的頁面標題、搜索框、 導航欄鏈接、多語言切換、倉庫鏈接，它們均取決於你的配置。在 .vupress/config.js 文件添加一些導航欄鏈接：

module.exports = {
	themeConfig: {
	  	// 你的GitHub倉庫，請正確填寫
	    repo: 'https://github.com/xxxxxxx/blog-demo',
	    // 自定義倉庫鏈接文字。
	    repoLabel: 'My GitHub',
	  	nav: [
	  		{ text: 'Home', link: '/' },
	  		{ text: 'FirstBlog', link: '/blog/FirstBlog.md' }
	  	]
	}
}

接着，我們在 docs 目錄下新建 blog 文件夾，在 blog 目錄下創建 /blog/FirstBlog.md 作爲我們第一篇博客的內容：

# 我的第一篇博客

My First Blog

我們再在項目根目錄，即 blog-demo 下，輸入命令 npm run docs:dev ，瀏覽器中訪問 http://localhost:8080/blog-demo/ 查看頁面效果，點擊頁面右上角的FirstBlog 可以看到我們第一篇博客：

側邊欄

最後我們配置側邊欄，讓用戶體驗更好一些，在 .vupress/config.js 文件添加一些代碼：

module.exports = {
  themeConfig: {
    sidebar: [
      ['/', '首頁'],
      ['/blog/FirstBlog.md', '我的第一篇博客']
    ]
  }
}

本地預覽

至此我們已經完成了一個最簡單的博客，再次運行項目，點擊首頁的按鈕 快速上手 ，我們可以看到：

部署

最後一步，我們需要將代碼部署到GitHub Pages，具體請參照文檔：Vupress-部署。

1、首先確定你的項目是否滿足以下條件：

• 文檔放置在項目的 docs 目錄中
• 使用的是默認的構建輸出位置
• VuePress 以本地依賴的形式被安裝到你的項目中，在根目錄的 package.json文件中有如下兩段代碼：

// 配置npm scripts
"scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
 }

// VuePress 以本地依賴的形式被安裝
"devDependencies": {
    "vuepress": "^0.14.8"
}

2、在github上創建一個名爲 blog-demo 的倉庫，並將你的代碼提交到github上。如果你對git不熟悉，請先閱讀：Git教程-廖雪峯的官方網站

3、在 docs/.vuepress/config.js 文件中設置正確的 base。

如果打算髮布到 https://<USERNAME>.github.io/<REPO>/（也就是說你的倉庫在 https://github.com/<USERNAME>/<REPO>），則將 base 設置爲 /<REPO>/，此處我設置爲 /blog-demo/ 。

4、在項目根目錄中，創建一個如下的 deploy.sh 腳本文件，請自行修改github倉庫地址

#!/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 [email protected]:<USERNAME>/<REPO>.git master:gh-pages

cd -

5、雙擊 deploy.sh 運行腳本，會自動在我們的 GitHub 倉庫中，創建一個名爲 gh-pages 的分支，而我們要部署到 GitHub Pages 的正是這個分支。

6、這是最後一步了，在 GitHub 項目點擊 Setting 按鈕，找到 GitHub Pages - Source，選擇 gh-pages 分支，點擊 Save 按鈕後，靜靜地等待它部署完成即可。

• 部署效果預覽：https://olewahhh.github.io/blog-demo/
• GitHub倉庫地址：https://github.com/olewaHHH/blog-demo