2. 程式人生 > 其它 >使用Jekyll + Github Pages搭建靜態網站

使用Jekyll + Github Pages搭建靜態網站

阿新 • • 發佈：2022-04-10

今天折騰 hugo + stack 主題翻車了，然後就想著試試用Jekyll來搭建個人部落格。

Jekyll 是 Github Pages 官方支援的靜態網站生成工具，優點是在可以直接github上編輯md，提交後，github會承擔生成html的工作。而使用hugo等工具，需要先在本地將md檔案渲染成html，然後上傳。

hugo的優點是快！

看了幾個jekyll主題，發現 chirpy 最得我心。cotes2020/jekyll-theme-chirpy: A minimal, responsive, and powerful Jekyll theme for presenting professional writing (github.com)

本文記錄Jekyll和chirpy的搭配使用。

安裝Ruby和Jekyll

jekyll也很麻煩，要安裝的東西一大堆：

Follow the instructions in the Jekyll Docs to complete the installation of Ruby, RubyGems, Jekyll, and Bundler.

  1. Download and install a Ruby+Devkit version from RubyInstaller Downloads. Use default options for installation.

  2. Run the ridk install

    step on the last stage of the installation wizard. This is needed for installing gems with native extensions. You can find additional information regarding this in the RubyInstaller Documentation

    第一次接觸ruby，完全懵逼，不知道裝了些啥，接近1個GB。列印的日誌是清新脫俗。

  3. Open a new command prompt window from the start menu, so that changes to the PATH

    environment variable becomes effective. Install Jekyll and Bundler using gem install jekyll bundler

  4. Check if Jekyll has been installed properly: jekyll -v

到這裡，本地環境就安裝好了。

Chirpy主題的使用

Install

Creating a New Site

跟著這裡操作。簡言之，使用其提供的 template repo 建立自己的 repo，命名為<GH_USERNAME>.github.io。

Installing Dependencies

將建立的 repo（<GH_USERNAME>.github.io） clone 到本地，執行：

git clone [email protected]:<GH_USERNAME>/<GH_USERNAME>.github.io
cd <GH_USERNAME>.github.io
bundle

依賴安裝完後，生成一個Gemfile.lock檔案。

<GH_USERNAME>.github.io裡面有一個Gemfile檔案，它指定了你想要使用的gem的位置和版本。

bundle命令根據Gemfile檔案安裝依賴，並將安裝的每個依賴的版本，記錄在Gemfile.lock檔案裡。這樣，當相同的庫或是專案在另一臺機器上載入時，執行bundle install將安裝完全相同的版本，而不是最新的版本。(在不同的機器上執行不同的版本可能會導致測試失敗等等)。簡單來說就是保證在不同環境下gem版本相同。

Gemfile.lock檔案可以提交到github，讓github pages的deploy 指令碼也使用相同的版本。但是，由於我是在Windows上執行bundle的，github pages的部署環境是linux。因此，需要執行以下命令，將 x86_64-linux 平臺的一些庫新增到Gemfile.lock裡面（只有幾個，多數是跨平臺相容的）：

bundle lock --add-platform x86_64-linux

Configuration

主要就是修改如下幾個檔案：

_config.yml

timezone: Asia/Shanghai
google_site_verification: googledxxxxxxx.html # 去Google Search Console申請，用於google收錄
avatar: assets/img/avatar/wy-avatar-339x335.jpg # 頭像
comments:
  active: utterances # 使用github issue作為文章的評論系統
  utterances:
    repo: whuwangyong/whuwangyong.github.io        # <gh-username>/<repo>
    issue_term: title  # < url | pathname | title | ...>
paginate: 20

_tabs/about.md

自定義“關於我”的內容。

favicon

自定義網站圖示。將favicon.ico檔案放入assets/img/favicons/。Customize the Favicon - Chirpy (cotes.page)

_data/share.yml

配置文章的分享選項，如Facebook、微博之類的。

Writing a New Post

Writing a New Post | Chirpy (cotes.page)

  • 在_posts目錄下建立YYYY-MM-DD-TITLE.md檔案即可，必須按照此格式命名。可以使用子目錄，用於分類
  • 圖片必須放在/assets/下。最佳實踐：放在/assets/img/posts/[YYYY-MM-DD-TITLE]目錄下

Front Matter

---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT # 2022-01-01 13:14:15 +0800 只寫日期也行；不寫秒也行；這樣也行 2022-03-09T00:55:42+08:00
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]     # TAG names should always be lowercase

author: # 不寫預設就是自己
  name: Full Name
  link: https://example.com

# 以下預設false
math: true
mermaid: true
pin: true
---

分類

支援多層級。如categories: [Java, Spring, AOP]，最終的分類效果是Java/Spring/AOP，這樣就可以複用筆記軟體裡面設定好的分類。

標籤

該主題的作者建議，TAG names should always be lowercase。我猜測這麼做的原因是，大小寫混用會導致相同含義的標籤以多種形式出現，如：VSCode、VScode、vscode。學到了。在我的筆記軟體裡面，大小寫混用的標籤正讓我苦不堪言。

img_path

當文中很多圖片具備共同的字首時，可以將該字首提取出來，放在Front Matter。

Liquid Codes

舉例：如果你在正文中新增如下內容，則會輸出該文章的標題。

{{ page.title }}

更多參考：Liquid 模板語言中文文件 | Liquid 中文網 (bootcss.com)

Running Local Server

You may want to preview the site contents before publishing, so just run it by:

bundle exec jekyll s

After a while, the local service will be published at http://127.0.0.1:4000 .

Deployment

Deploy by Using Github Actions。直接提交到github即可。

Upgrading

如前文所述，依賴的庫及其版本都指定在Gemfile 裡面，因此，修改此檔案，更新jekyll-theme-chirpy的版本號即可：

- gem "jekyll-theme-chirpy", "~> 3.2", ">= 3.2.1"
+ gem "jekyll-theme-chirpy", "~> 3.3", ">= 3.3.0"

And then execute the following command:

bundle update jekyll-theme-chirpy

As the version upgrades, the critical files (for details, see the Startup Template) and configuration options will change. Please refer to the Upgrade Guide to keep your repo’s files in sync with the latest version of the theme.

釋出時間與更新時間

chirpy主題還有個優點：自帶文章的更新時間。
​
這就不需要倒騰額外的jekyll外掛去實現這個功能了。如gjtorikian/jekyll-last-modified-at: A Jekyll plugin to show the last_modified_at time of a post. (github.com)

新增tab到左側欄

如新增“友情連結”tab。在_tabs目錄下新建links.md:

---
title: 友情連結
icon: fas fa-link
order: 5
---

調整order和icon。icon去Font Awesome Icons裡面找。然後修改_data/locales/en.yml和_data/locales/zh-CN.yml，在tabs:下新增links: Links和links: 友鏈，以適配中英文。

進階內容

用了兩天，對Jekyll + Github Pages 的工作邏輯有了一些理解。

為什麼使用Jekyll可以直接提交md

在<github_username>.github.io根目錄下，檢視.github/workflows/pages-deploy.yml檔案：

name: 'Automatic build'
on:
  push:
    branches:
      - main
    paths-ignore:
      - .gitignore
      - README.md
      - LICENSE

jobs:
  continuous-delivery:

    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0  # for posts's lastmod

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.7
          bundler-cache: true

      - name: Deploy
        run: bash tools/deploy.sh

該檔案定義了一個workflow：當push程式碼到main分支時，執行jobs裡面定義的動作。最關鍵的是Deploy這一步，它執行了一個指令碼：tools/deploy.sh。這個指令碼做的事情，就是執行bundle exec jekyll build -d _site將md檔案編譯為html，生成靜態網站，然後將_site下的內容push到gh-pages分支。到這裡就很清楚了，是github幫助我們執行了build操作，將md轉換成了html。

在github上檢視你的github.io專案，在Actions下面可以看到每次提交新文章時觸發的workflows：
​
第一個workflow就是上面提到的.github/workflows/pages-deploy.yml，第二個是github pages建立的，可以看到bot標誌。點進workflow runs，可以看到執行的日誌，根據日誌能更加清楚的知道背後的流程。

如果使用hugo建站，github後臺並沒有hugo的環境，所以不能幫助我們編譯md。這就需要我們自己編譯好html，然後push到github.io專案。push之後的流程是一樣的：由github pages的bot將編譯好的靜態網站釋出到https://<username>.github.io。

自定義workflow

  • 以修改tools/deploy.sh

第一個親測可行，後兩個還沒研究。

netlify、vercel是什麼

除了github pages，還有netlify、vercel等也能生成並部署靜態網站。它們從<username>.github.io 的main分支拉取md原始檔，然後在自己的資源上執行bundle jekyll exec build，將build之後的html放在它們自己的伺服器上，並提供一個域名供你訪問這個靜態站點。
除了Jekyll，它們還支援Hugo、Hexo、Next.js等多種靜態網站構建工具。也就是說，只將github作為一個程式碼託管平臺，裡面可以放Jekyll、Hugo等多種構建工具和md檔案，netlify和vercel都可以將它們編譯為html併發布出去。從這個方面說，它們比github強大。

Jekyll的Markdown處理器

Jekyll預設的Markdown Processor是kramdown，這與我們常使用的typora、vscode的md解析器不同。kramdown會將pipe字元|解析為table語法。如果正文中有link或者image語法，且文字包含了|字元，需要對其進行轉義。下述這種寫在程式碼塊裡面可以，如果寫在正文，就會當成表格了。

[A | B](http://foo.com)
[img | 1](http://img.com/1.jpg)

這個問題2014年就有人提了，但是作者一直沒修復：

  1. Pipes inside image alt text lead to unwanted table output · Issue #135 · gettalong/kramdown (github.com)
  2. the conditional probability equation doesn't display normal · Issue #46 · gettalong/kramdown (github.com)
  3. Kramdown bug - pipe character in Markdown link creates a table · Issue #2818 · jekyll/jekyll (github.com)
  4. markdown - How do you disable tables in Kramdown? - Stack Overflow
  5. 對 Markdown 渲染引擎 kramdown 的幾點 hack | 明無夢 (dreamxu.com)
  6. Table syntax · Issue #151 · gettalong/kramdown (github.com)
  7. Pipe characters in text creates table · Issue #317 · gettalong/kramdown (github.com)
  8. Bug - pipe character in Markdown link creates a table · Issue #431 · gettalong/kramdown (github.com) 這是2017年的issue，作者回復說2.x版本會修復，但仍然存在。在kramdown - syntax頁面，搜尋“Automatic and Manual Escaping”可以檢視kramdown所有（可能）需要轉義的字元。

所以，如果要繼續用kramdown，要麼禁用table語法，要麼把所有用到|的地方全部轉義。這兩個我都不會選：不用table不可能；為了適應kramdown修改標準的md語法更不可能。

更改Jekyll的markdown處理器

鑑於kramdown的上述問題，我嘗試給Jekyll換一個Markdown處理器。根據文件Markdown Options - Jekyll，除了kramdown，Jekyll還支援jekyll-commonmark和jekyll-commonmark-ghpages。我分別試用了這兩個處理器，問題更多。尤其是jekyll-commonmark-ghpages，其相容的jekyll版本是3.9.x，與我使用的Chirpy主題（需要jekyll 4.x）不相容。jekyll-commonmark倒是解決了|的問題，但是程式碼高亮有問題，有些程式碼始終無法渲染，花了整整一天翻遍了github也沒找到jekyll-commonmark到底應該怎麼配置。不負責任的說一句，這就是個坑。

Jekyll也支援自定義處理器，我沒嘗試。另一個優質主題jekyll-TeXt-theme同樣用的kramdown。看來用Jekyll就避免不了kramdown。

搜尋功能

Chirpy主題的作者在這裡提到，他使用的是Simple-Jekyll-Search實現的搜尋功能。效果不錯，速度飛快。

提交到谷歌/百度等搜尋引擎

顯示閱讀量

Reference

  1. Getting Started | Chirpy (cotes.page)
  2. https://blog.csdn.net/qq_38534524/article/details/108462825

本文同步釋出於：

相關推薦

使用Jekyll + Github Pages搭建靜態網站

今天折騰 hugo + stack 主題翻車了，然後就想著試試用Jekyll來搭建個人部落格。

使用 Jekyll 和 Github Pages 構建靜態部落格

# 準備工作 - 假定你會使用 Git 和 Github - 你懂一線前端的知識 - 你有一定的英語基礎

ECS訓練營Day1—基於阿里雲ECS、VuePress搭建靜態網站

一、概述 VuePress是2018年由尤雨溪釋出的一個全新的基於Vue的靜態網站生成器，它是一個非常輕量級的靜態網站生成器。VuePress主要用於生成技術文件，其類似於Gitbook，我們可以用於部落格或文件說明，並且我們不僅

用GitHub Pages搭建部落格（四）

本篇介紹配置網站引數及釋出文章 GitHub Pages一般使用的Jekyll，配置項基本都設定在_config.yml檔案中，在此檔案中，按引數描述進行配置即可。此處以上一篇使用的Jekyll主題為例進行介紹。

使用Gridea+Github Pages搭建個人部落格並繫結域名

建立GitHub Pages倉庫 在GitHub首頁，點選+號->New repository 倉庫的名稱必須是使用者名稱.github.io（我已經建立過這個倉庫，所以會報錯）

jekyll+github pages

寫在前面 這篇文章記錄了我折騰jekyll,github pages的過程，看到別人的 xxxx.github.io，於是我也想搞一個，瞭解到大都使用的jekyll來生成的。最開始我還不知道可以直接fork別人在github上面搞好的jekyll blog，然後

如何在 GitHub 上搭建個人網站（github.io）

前言 目前，想要搭建自己的部落格、個人主頁、線上簡歷、專案演示，大部分同學選擇購買雲伺服器+域名，我也在阿里雲購買了雲伺服器+域名，不過也有同學想要免費的服務，就可以使用 GitHub 提供的免費 Pages服務：gi

使用vuepress搭建GitHub pages靜態部落格頁面

vuepress官網vuepress是尤大開發來寫文件的靜態頁面。可以用Markdown 語法，並且也可以使用vue模組化的方式開發頁面。

GitHub Pages + Hexo搭建個人部落格網站-github風格-採坑記錄

目錄 1.本機安裝nodejs 2.github上建立倉庫 3.安裝hexo 4.hexo主題 5.配置主題 6.新增文章

利用GitHub Pages和Jekyll建立個人部落格

雖然現在市面上已經有很多優秀的部落格服務商，但是擁有一個屬於自己的站點還是一件很有吸引力的事情。整個站點從頭到尾都可以完全按照自己的意願定製，並且可以完全避免各種礙眼的廣告。最重要的是，配上一個個性化

ECS7天實踐進階訓練營Day1：使用阿里雲ECS，快速搭建、管理VuePress靜態網站

一、概述 VuePress是2018年由尤雨溪釋出的一個全新的基於Vue的靜態網站生成器，它是一個非常輕量級的靜態網站生成器。VuePress主要用於生成技術文件，其類似於Gitbook，我們可以用於部落格或文件說明，並且我們不僅可

使用Github Pages構造屬於自己的部落格：如何在本地使用jekyll

Jekyll server本地預覽文章not found 解決方案： 找到檔案C:\\Ruby26-x64\\lib\\ruby\\2.6.0\\webrick\\httpservlet\\filehandler.rb，具體安裝目錄根據實際情況確定；

GitHub Pages 與 Gitee Pages 上的 Jekyll

GitHub 與 Gitee 提供的 Pages 服務中，均內嵌了 Jekyll 支援（Gitee 還提供了 Hugo 與 Hexo 支援）。本來我的Jekyll在github pages上，但是國內訪問太慢了，準備遷移到Gitee上，結果發現效果完全和Github上不同，必

使用 jsDelivr 免費加速 GitHub Pages 部落格的靜態資源（二）

之前寫過一篇 使用 jsDelivr 免費加速 GitHub Pages 部落格的靜態資源，在那之後，又陸續想到並實施了幾點利用 jsDelivr 進一步加速靜態資源載入的措施，新起一篇作為記錄和分享。

用Github Pages+Hexo搭建部落格之(七)如何刪除一篇已經發布的文章 #成功解決：同時刪除掉.deploy_git資料夾

【置頂】【專欄】用Github Pages+Hexo搭建部落格 文章目錄 【置頂】【專欄】[用Github Pages+Hexo搭建部落格](https://blog.csdn.net/qq_34243930/category_9662425.html)起因解決步驟總結具體步驟如下原

GitHub Pages + Jekyll 部署之後不能訪問

首先，部署成功的標誌是倉庫中的setting中已經顯示Your site is published a xxxxxx。 如下圖其次就是假如你的專案已經顯示了上面的綠色標誌，但是無法訪問，那麼問題肯定是dns的問題 dsn修改如下 223.5.5.

GitHub Pages Jekyll Liquid 時區timezone問題

在之前的文章GitHub Pages系列中，介紹了使用GitHub Pages搭建部落格。但實際執行一段時間後發現，文章顯示的時間是UTC時間，而不是北京時間。

GitHub Pages Jekyll 程式碼高亮

本文介紹Jekyll程式碼高亮 GitHub Pages目前使用的Jekyll 3.0，和我們部落格相關的特性就有：

搭建Github Pages部落格

Github Pages 首先介紹一下Github Pages，可以將其理解為：github給使用者提供的搭建部落格的託管工具。Github免費提供了300M的空間供你使用，日常記錄一些隨筆、技術筆記是完全沒有問題的。

Hexo+Gitee Pages 搭建個人靜態部落格

Hexo+Gitee Pages 搭建個人靜態部落格 有關搭建部落格類的教程我之前寫了不少，感興趣的小夥伴可以看看我的部落格專欄：