前言

我相信每一個(gè)程序員入門(mén)時(shí)敢靡，都經(jīng)歷過(guò)搭建一個(gè)個(gè)人博客這樣的階段。確實(shí)這是一個(gè)好的練手項(xiàng)目苦银，而搭建博客難度也可高可低啸胧，取決于個(gè)人目標(biāo)。本文提供了一個(gè)選擇幔虏，可基于 GitHub 的 GitHub Pages 功能 和 Vuepress 框架快速地搭建免費(fèi)的markdown博客：

• 對(duì)于文檔編寫(xiě)者來(lái)說(shuō)纺念，能更專(zhuān)注于寫(xiě)文章
• 對(duì)于文檔開(kāi)發(fā)者來(lái)說(shuō)，一切皆Vue組件想括，能方便地自定義主題

Vuepress官網(wǎng)：https://vuepress.vuejs.org/zh/

基本工具

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

構(gòu)建基本項(xiàng)目結(jié)構(gòu)

1. 新建一個(gè)名為 blog-demo 的文件夾陷谱，命令行進(jìn)入到該文件夾目錄，輸入命令：

# 按默認(rèn)配置初始化一個(gè)項(xiàng)目瑟蜈，此時(shí)會(huì)在當(dāng)前目錄下生成 package.json 文件
npm init -y

2. 將 VuePress 作為一個(gè)本地依賴(lài)安裝

npm install -D vuepress

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

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

4. 在項(xiàng)目根目錄下，新建 docs 文件夾

mkdir docs

5. 新建一個(gè) markdown 文件

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

6. 輸入命令啟動(dòng)項(xiàng)目铺根，在瀏覽器中訪問(wèn) http://localhost:8080/ 即可預(yù)覽效果

npm run docs:dev

基本配置

現(xiàn)在我們已經(jīng)構(gòu)建出了最基本的項(xiàng)目結(jié)構(gòu)宪躯，并且可以在瀏覽器中預(yù)覽到 docs 目錄下的 README.md 文件的效果，該文件即是我們網(wǎng)站的首頁(yè)位迂，如圖所示：

基本效果

然而如果沒(méi)有任何配置访雪，用戶(hù)將無(wú)法在網(wǎng)站上自由導(dǎo)航。因此掂林，為了更好地自定義我們的網(wǎng)站臣缀，我們接著在 docs 目錄下新建 .vuepress 文件夾，執(zhí)行命令如下：

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

接著在 .vuepress 文件夾下新建 config.js 文件,這里的 config.js 便是一個(gè) Vuepress 網(wǎng)站必要的配置文件党饮，在其中添加如下代碼：

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

其中配置項(xiàng)的含義為：

• base：站點(diǎn)的基礎(chǔ)路徑肝陪，它的值應(yīng)當(dāng)總是以斜杠開(kāi)始驳庭，并以斜杠結(jié)束刑顺。這里設(shè)置為 /blog-demo/ 氯窍，我們?cè)俅卧诒镜剡\(yùn)行項(xiàng)目，訪問(wèn)路徑就需要變更為 http://localhost:8080/blog-demo/
• title：網(wǎng)站的標(biāo)題
• description：網(wǎng)站的描述

默認(rèn)主題配置

Vuepress 提供了一個(gè)默認(rèn)主題蹲堂，讓我們不必自己去從零實(shí)現(xiàn)復(fù)雜的 markdown 文件渲染狼讨、目錄結(jié)構(gòu)等，直接按照規(guī)則去使用它即可柒竞。如果你想自定義自己的主題政供，請(qǐng)查看官方文檔：Vuepress-開(kāi)發(fā)主題。

首頁(yè)

默認(rèn)主題提供了一個(gè)首頁(yè)的布局朽基，想要使用它布隔，需要在你的根級(jí) README.md 以格式 YAML front matter 指定 home: true。因此稼虎，將我們最初創(chuàng)建的 README.md 修改一下：

---
home: true
heroImage: /vue-logo.png
heroText: blog-demo
tagline: 博客示例
actionText: 快速上手 →
actionLink: /
features:
- title: 簡(jiǎn)潔至上
  details: 以 Markdown 為中心的項(xiàng)目結(jié)構(gòu)衅檀，以最少的配置幫助你專(zhuān)注于寫(xiě)作。
- title: Vue驅(qū)動(dòng)
  details: 享受 Vue + webpack 的開(kāi)發(fā)體驗(yàn)霎俩，在 Markdown 中使用 Vue 組件哀军，同時(shí)可以使用 Vue 來(lái)開(kāi)發(fā)自定義主題。
- title: 高性能
  details: VuePress 為每個(gè)頁(yè)面預(yù)渲染生成靜態(tài)的 HTML打却，同時(shí)在頁(yè)面被加載的時(shí)候杉适，將作為 SPA 運(yùn)行。
---

• heroImage: 首頁(yè)圖片柳击，圖片放置在 .vupress/public 文件夾下猿推，若沒(méi)有該文件夾則自己創(chuàng)建一個(gè)，保存一張你想要的首頁(yè)圖片腻暮，并在此處引用彤守。
• 其它參數(shù)請(qǐng)參考官方文檔：Vuepress-默認(rèn)主題首頁(yè)

導(dǎo)航欄

導(dǎo)航欄可能包含你的頁(yè)面標(biāo)題、搜索框哭靖、 導(dǎo)航欄鏈接具垫、多語(yǔ)言切換、倉(cāng)庫(kù)鏈接试幽，它們均取決于你的配置筝蚕。在 .vupress/config.js 文件添加一些導(dǎo)航欄鏈接：

module.exports = {
    themeConfig: {
        // 你的GitHub倉(cāng)庫(kù)，請(qǐng)正確填寫(xiě)
        repo: 'https://github.com/xxxxxxx/blog-demo',
        // 自定義倉(cāng)庫(kù)鏈接文字铺坞。
        repoLabel: 'My GitHub',
        nav: [
            { text: 'Home', link: '/' },
            { text: 'FirstBlog', link: '/blog/FirstBlog.md' }
        ]
    }
}

接著起宽，我們?cè)?docs 目錄下新建 blog 文件夾，在 blog 目錄下創(chuàng)建 /blog/FirstBlog.md 作為我們第一篇博客的內(nèi)容：

# 我的第一篇博客

My First Blog

我們?cè)僭陧?xiàng)目根目錄济榨，即 blog-demo 下坯沪，輸入命令 npm run docs:dev ，瀏覽器中訪問(wèn) http://localhost:8080/blog-demo/ 查看頁(yè)面效果擒滑，點(diǎn)擊頁(yè)面右上角的FirstBlog 可以看到我們第一篇博客：

本地效果預(yù)覽

側(cè)邊欄

最后我們配置側(cè)邊欄腐晾，讓用戶(hù)體驗(yàn)更好一些叉弦，在 .vupress/config.js 文件添加一些代碼：

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

本地預(yù)覽

至此我們已經(jīng)完成了一個(gè)最簡(jiǎn)單的博客，再次運(yùn)行項(xiàng)目藻糖，點(diǎn)擊首頁(yè)的按鈕 快速上手 淹冰，我們可以看到：

我的第一篇博客

部署

最后一步，我們需要將代碼部署到GitHub Pages巨柒，具體請(qǐng)參照文檔：Vupress-部署樱拴。

1、首先確定你的項(xiàng)目是否滿(mǎn)足以下條件：

• 文檔放置在項(xiàng)目的 docs 目錄中
• 使用的是默認(rèn)的構(gòu)建輸出位置
• VuePress 以本地依賴(lài)的形式被安裝到你的項(xiàng)目中洋满，在根目錄的 package.json文件中有如下兩段代碼：

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

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

2晶乔、在github上創(chuàng)建一個(gè)名為 blog-demo 的倉(cāng)庫(kù)，并將你的代碼提交到github上牺勾。如果你對(duì)git不熟悉瘪弓，請(qǐng)先閱讀：Git教程-廖雪峰的官方網(wǎng)站

3、在 docs/.vuepress/config.js 文件中設(shè)置正確的 base禽最。

如果打算發(fā)布到 https://<USERNAME>.github.io/<REPO>/（也就是說(shuō)你的倉(cāng)庫(kù)在 https://github.com/<USERNAME>/<REPO>）腺怯，則將 base 設(shè)置為 /<REPO>/，此處我設(shè)置為 /blog-demo/ 川无。

4呛占、在項(xiàng)目根目錄中，創(chuàng)建一個(gè)如下的 deploy.sh 腳本文件懦趋，請(qǐng)自行修改github倉(cāng)庫(kù)地址

#!/usr/bin/env sh

# 確保腳本拋出遇到的錯(cuò)誤
set -e

# 生成靜態(tài)文件
npm run docs:build

# 進(jìn)入生成的文件夾
cd docs/.vuepress/dist

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

# 如果發(fā)布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

5晾虑、雙擊 deploy.sh 運(yùn)行腳本，會(huì)自動(dòng)在我們的 GitHub 倉(cāng)庫(kù)中仅叫，創(chuàng)建一個(gè)名為 gh-pages 的分支帜篇，而我們要部署到 GitHub Pages 的正是這個(gè)分支。

分支提交

• 部署效果預(yù)覽：https://olewahhh.github.io/blog-demo/
• GitHub倉(cāng)庫(kù)地址：https://github.com/olewaHHH/blog-demo
  
  Setting
  
  
  設(shè)置