手把手帶你用 VuePress + Github Pages 搭建博客

2022-01-12 前端開發博客
大家好，我是漫步，新的一年快來了，也許你會想要搭建一個屬於自己的博客，冴羽的這篇文章應該能幫到你。喜歡記得關注我並設為星標。前言

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

點擊 「閱讀原文」，可直接訪問，接下來我們看下具體搭建的步驟：0. VuePress

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

1. 本地搭建

快速開始同 VuePress 官網：

// 文件名自定義
mkdir vuepress-starter && cd vuepress-starter
yarn init # npm init
yarn add -D vuepress # npm install -D vuepress
創建你的第一篇文檔，VuePress 會以 docs 為文檔根目錄，所以這個 README.md 相當於主頁：
mkdir docs && echo '# Hello VuePress' > docs/README.md
在 package.json 中添加一些 scripts
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
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
創作不易，加個點讚、在看 支持一下哦！

相關焦點

  • 現在還有1%的程式設計師不會搭建博客,是你嗎?
    在 2020 年如果還沒有自己的技術博客確實有點落伍了，但是搭建自己的技術博客有很多種技術方案，我知道的有  Hexo, jeklly, vuepress  等。寵粉無邊，所以儘量所有的技術方案都手把手教大家一輪，讓大家都有自己的個人博客。
  • 使用GitHub和阿里雲效自動發布博客
    前言我接觸過很多博客平臺：WordPress、Jekyll、Hexo、Typecho和Vuepress，有的是靜態博客有的需要伺服器運維，玩過花裡胡哨後私以為博客最重要的是思考和記錄，而不是不停地裝飾。所以總結一些經驗可以讓大家快速把博客搭建起來，並且不會憂愁後續的維護。
  • 零代碼教你用 GitHub 搭建個人博客!
    公眾號關注 「GitHubDaily」設為 「星標」，每天帶你逛
  • 可能是最全面的github pages搭建個人博客教程
    Git倉庫首先你要在github上有自己博客倉庫，用來生成和存放博客文章。你可以直接fork我的博客倉庫。這樣你馬上有了自己的博客倉庫。點這裡https://github.com/lemonchann/lemonchann.github.io我的博客地址進去fork，之後在你自己的倉庫下會看到剛複製的倉庫。以後的操作都在你自己的倉庫進行。
  • 一看就會的保姆級教程,10分鐘搭建個人博客
    Part1前言相信很多人都想擁有一個自己的個人博客，現有的個人博客搭建框架已經有很多了，例如 hexo 、vuepress 、jekyll 等等，這裡我選用 vuepress 來快速搭建個人博客網上教程千千萬，但總歸都是零零散散的，沒人會給你講解得清清楚楚，所以我這裡就手把手來講解一下如何從零搭建
  • Github + Hexo 搭建博客
    最近突然想起自己之前還用 Github + Hexo 搭建過自己的博客，找到源碼一看還是 2017
  • 途牛原創 如何使用 hexo+github 搭建個人博客
    如果你不想要像新浪、csdn 這類樣式醜、頁面內容雜的博客網站，或者不想在移植、遷移上浪費精力，又或者不想付出多餘的銀子買VPS，那麼 GitHub Pages 是不錯的選擇。GitHub Pages 有以下幾個優點：輕量級的博客系統，沒有麻煩的配置免費空間，享受 Git 版本管理功能使用標記語言，比如 Markdown無需自己搭建伺服器可以綁定自己的域名當然他也有缺點：搭配模板系統，相當於靜態頁發布，每運行生成一次都必須遍歷全部的文本文件，網站越大，生成時間越長
  • 使用Hexo+Github搭建個人博客網站
    下面，我將會介紹如何來使用Hexo+Github搭建個人博客網站。為了順利地完成個人博客網站的搭建，需要做以下準備工作：安裝Hexo（命令為npm i -g hexo）;搭建博客下面將分步來介紹如何使用Hexo和Github來搭建個人博客網站。
  • 如何用 GitHub 從零開始搭建一個博客?
    公眾號關注 「GitHubDaily」設為 「星標」，
  • Hexo+Github/Gitee 搭建個人博客
    如果你有總結整理的習慣，可以考慮搭建一個個人博客，把文章發布在上面，相比於其它平臺，
  • 從零開始搭建個人博客(一)- 使用hugo搭建個人博客
    >>> brew install hugo>>> hugo versionhugo v0.89.4+extended darwin/arm64 BuildDate=unknown創建站點創建一個站點 left-pocket-test， 並進入到站點根目錄。
  • 如何用 GitHub 從零開始搭建一個博客 ?
    搭建個人博客的文章：【新手向】從零開始搭建一個酷炫免費的個人博客但有些細節方面寫的不是很清楚，依舊有很多小夥伴來反饋沒有搭建成功。今天周末就跟大家分享一篇文章，細節滿分，教你如何一步步使用 GitHub 搭建出個人博客。按照步驟一步步操作下去，你肯定能擁有一個自己的博客，Let's go !準備條件在這裡先跟大家說一些準備條件，有些同學可能一聽到搭建博客就望而卻步。弄個博客網站，不得有臺伺服器嗎？不得搞資料庫嗎？不得註冊域名嗎？
  • 用 GitHub + Hexo 建立你的第一個博客
    建立博客的通常渠道包括：在博客平臺上註冊，比如 博客園、CSDN、新浪博客 等。利用博客框架搭建，如 WordPress、Jekyll、hexo 等。自己用代碼寫一個。其中，第一種最簡單，也最受限，說不定還會被刪帖刪號。第二種稍複雜，另外需要自己找部署的伺服器，但可定製化較高，是很多程式設計師的選擇。
  • 一杯茶的時間,上手 Gatsby 搭建個人博客
    Gatsby 項目結構建議使用 Starter 修改著理解 Gatsby，我用的是 Gatsby + Netlify CMS Starter[11]。完整的 Gatsby 項目結構可以看文檔[12]，這裡針對搭建博客用到的功能說明一下。
  • 一行代碼不用寫:GitHub博客小白版入門教程
    利用GitHub Pages平臺，就可以搭建非常好用的個人博客。但是難點在於，你在要敲很多代碼才能搭出一個博客。對於小白和新手來說，太不友好。沒關係！現在不用寫代碼也可以了。不需要敲碼，不用寫使用命令行，可以自定義主題，還能有自己的域名。Fast.ai提供了模版，只要註冊一個github帳號，小白就能夠完成搭建博客的操作。
  • 個人博客|第一章|手把手教你搭建、上線個人博客
    」前言Hello，我是淡漠，今天帶大家一起搭建個人博客。個人博客一直都是非常受歡迎的個人項目，個人博客分靜態和動態兩種，淡漠個人比較青睞靜態博客，靜態不需要管理後端，相比動態博客，靜態博客可以不需要花一分錢，開發成本要低一些，畢竟作為學生黨，買伺服器放一個博客網站有點浪費，也可以把精力集中於寫博客，而不是開發博客。
  • 手把手免費搭建個人博客網站
    官網商城類可以去凡客，博客框架可以使用wordpress或者Hexo。2.GitPage簡介GitPage 與 GitHub 同屬一個組織 GitHub Inc.，可以說 GitPage 出生的目的就是為了服務於GitHub，GitHub 上有眾多非常優秀的開源項目，有些項目比較大，涉及到框架級別的項目它的Readme.txt就能講清楚的，於是 GitPage 誕生了，GitPage 允許你將你的博客創建為一個 GitHub Project，通過 your-account.github.io 這樣的特殊項目名稱與 GitPage 進行關聯。
  • 手把手教你用Django搭建博客(二)
    作者：楊學光博客：http://zmrenwu.com/往期精彩連載：Django之簡化版Pinterest手把手教你用Django搭建博客（一）3、建立 Django 博客應用建立博客應用我們已經建立了
  • 如何搭建一個比簡書更精美的個人博客
    幸好我們生存在一個開源的時代，今天小編就用hexo，帶你搭建一個比簡書更精美的個人博客。但人各有所愛，並不應該強迫大家都用相同的主題，因此我們要挑選主題。我們也還需要其他方案——利用github來建立自己的主頁。
  • 手把手搭建個人博客(圖文教程)
    首先我們談一談搭建個人博客必要性，個人認為在學習過程中，被動接受知識對你的提高是輕微的。可見搭建個人博客是非常有必要的，很多讀者很早就要求我發一篇搭建個人博客的文章，由於個人時間願意本來想直接轉載，但是在自己實際操作中遇到很多坑，浪費不少時間，都是把主要步驟給出且時間久遠，沒有詳細的圖文配合。