Jekyll 搭建 github page

如果今天想要搭建一個Blog或是個人網站甚至是一個公司產品的網站，卻又懶得去租用一個VPS伺服器，這篇文章會是一個不錯的教學。因為其實每一個人的github都可以搭建成一個靜態網站，而每一個repo都可以搭建成子網站，換言之。可以在這樣子的github page架構下搭建很多很多很多的網站。

• 環境搭建
• 生成網站
  • 無中生有初始化一個網站
  • github page
    • 現成模板
      • 分叉 變成 主網頁
      • 分叉 變成 子網頁
• _config.yml文件修調整
• _post 資料夾
• build 出 靜態網站文件
  • 本地server
    • 自動發布 github page
• Markdown 語法
• 進階
  • 圖片大小、位置控制
  • 表格欄位內的換行
  • 數學公式
  • 任務列表
  • 加入 Open Graph 讓你的連結有縮圖
    • 指定 標題
    • 指定 簡介
    • 添加 圖片縮圖
  • 新增頁面
  • 添加翻頁功能
• 參考文獻

環境搭建

在搭建網站之前，我們需要先設定好我們的環境，這樣才可以執行jekyll運作起來我們的部落格或是網站。 主要依賴 gem指令，他好像是ruby。但我使用的是mac os 他本身自帶。剩下需要做的事gem install jekyll

生成網站

無中生有初始化一個網站

在當前目錄下生成一個blog資料夾，並前初始化為靜態網站

jekyll new blog

進去之後運行 jekyll serve就可以在http://127.0.0.1:4000 或是 http://localhost:4000看到最乾淨的網站了。

github page

來到我一個最重要的一步，我們中了伺服器不是為了在本地端開一個伺服器出來。是為了能夠生成一個文件丟到github上面，進一步讓我變成一個靜態的網頁託管。 這是我們開始一個repo，命名為xxx.github.io 這邊的xxx是你賬戶註冊所使用的用戶名稱，衹要有一點點的差異就是不會成功了。現在我們把這個repoClone 下來，再把我們剛剛申請的所有的靜態網站，全部丟進去。做一個 add commit push基本上再過不久的時間，你就可以看到他了。他會出現在xxx.github.io在網址當中。通常需要最快30秒，最長差不多四五分鐘的反應時間。他並不會立刻馬上的出現在你的網頁上面。

現成模板

因為在jekyll已經不是什麼小項目了，他已經存在了非常多年，所以也會有許多熱情的開發者撰寫了很多公開的模板給大家使用，http://jekyllthemes.org，如果在裡面有你看起來高興的樣子，就可以直接拿來用，直接fork一個很快的。這樣可以省去很多開發時間，也對一個小白是非常友善的。 所以如果挑到喜歡的，那就讓我們分叉一個吧。 個人覺得很有意思的模板：

• Windows 95
  

分叉 變成 主網頁

github會給每個user 一個網址，只是看你有沒有拿來用而已，預設是xxx.github.io，其中xxx是你自己的名字。 你只要把你fork出來的repo，點擊該repo頁面的右上角的setting ，重新命名該repo為xxx.github.io的格式，過個幾分鐘你就可以進到xxx.github.io的網站了。

分叉 變成 子網頁

子網頁是指我們不是xxx.github.io，我們把網頁搭載xxx.github.io/repo名稱，這是你fork完，依樣把repo 重新命名一下，應該就要在xxx.github.io/repo名稱下看到自己的內容了。如果沒看到可以檢查一下repo中的setting，下面會有GitHub Pages 相關的設定，可能是因為為他就線在其他的分支了。

補充說明 通常我們會把 生成靜態網頁前的原始碼放在 master 分支，把生成玩的靜態網頁放在gh-pages分支。不知哪來的傳統，不過現在github 設定裡面也支持，指定要用哪個branch呈現網頁的選項。

_config.yml文件修調整

會來到這裡，就代表著你已經從模板庫裡面找到了一個不錯的網站做樣本。可是你從模板庫裡面拿到了網站，裡面預設的信息基本上都是別人家的blog或是公司，所以現在我們要把它變成自己的網頁，我們要來修改我們自己的個人信息，那麼裡面的詳細細節，每一個模板都會有不太一樣，所以建議大家還是一一的看一下自己的檔案慢慢的修改，它裡面都一定會有提示。

_post 資料夾

這是一個資料夾這是博客文章的地方。 基本上每一個文件頂部有詳細的要求，如果並文章內的YAML頭部沒有按照這樣子的規則去撰寫的話，它會完全無法識別。

在預設的情況下，這個資料夾裡面本來就會存放一些文章。你可以大概學習一下別人大概是怎麼樣去撰寫一篇文章的。 基本上每一個文章的開頭都有詳細的YAML的格式設定。當中比較特別的是第一行layout: post，這邊定義了呈現的頁面樣式，而頁面樣式在_layouts資料夾中有詳細的定義。

build 出 靜態網站文件

會走到這裡代表你的_config文件已經設定完成，還有已經設定好一些文章可以發佈了，即使沒有文章也沒關係。

這個時候我們進到總目錄底下執行jekyll build 就可以順順利利的製作一個網站出來。如果順利運作成功的話，你可以在目錄底下看到很多html的文件。在其中，index.html最為重要，因為它是流覽你網頁的第1個頁面。 所以現在你有Index.html的文件了。這時的你可以嘗試用瀏覽器看，看看這個文件，看看是否順利的可以開起來。

本地server

當我們製作好，文件夾好，其實jekyll同時也支持伺服器。你衹要在根目錄底下執行jekyll serv 你就會在本地端啟動一個伺服器出來。這個伺服器是HTTP的伺服器，同時它也會開啟一個4000端口出來。所以你這時開啟一個瀏覽器輸入http://127.0.0.1:4000 或是 http://localhost:4000 就可以順利的造訪這個網頁。 值得一提的是，這個伺服器是隨時更新的，他會無時無刻，偵測你在資料夾裡面的檔案變動。他衹要一發現有一些檔案被修改了，他就會立刻去重新建立一個新的網頁出來。而且執行的速度非常快，他可以讓你在最快的時間內看到你的網頁變化。

自動發布 github page

為了使得發布更加的快速，做了自動 add, commit, push 的腳本 首先在目錄底下執行 nano publish.sh，創建一個文黨貼上去，contral+o儲存，contral+x退出

jekyll build; git commit -am $1 ; git add . ;git push origin master

使用方法sh publish.sh "更新的commit message"，就會自動更新勒。

Markdown 語法

• MarkDown語法大全
• Markdown語法教學

進階

圖片大小、位置控制

[來自這裡]
預設的圖片效果：
原始碼：

![](/images/doge.png)

大小、位置控制：
原始碼：

<div align="center"><img width="65" height="75" src="/images/doge.png"/></div>

表格欄位內的換行

[來自這裡]
範例程式碼：

| Header1 | Header2                          |
|---------|----------------------------------|
| item 1  | 1. one<br />2. two<br />3. three |

效果：

Header1	Header2
item 1	1. one 2. two 3. three

數學公式

[來自這裡]
如果是在 GitHub Pages，可以參考 http://wanguolin.github.io/mathmatics_rending/ 使用 MathJax 來優雅地展示數學公式（非圖片）。

如果是在 GitHub 項目的 README 等地方，目前我能找到的方案只能是貼圖了，以下是一種比較方便的貼圖方案：

1. 在 https://www.codecogs.com/latex/eqneditor.php 網頁上部的輸入框裡輸入 LaTeX 公式，比如 $$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$。

2. 在網頁下部拷貝 URL Encoded 的內容，比如以上公式生成的是 https://latex.codecogs.com/png.latex?%24%24x%3D%5Cfrac%7B-b%5Cpm%5Csqrt%7Bb%5E2-4ac%7D%7D%7B2a%7D%24%24。

3. 在文檔需要的地方使用以上 URL 貼圖，比如: 原始碼：

   ![](https://latex.codecogs.com/png.latex?%24%24x%3D%5Cfrac%7B-b%5Cpm%5Csqrt%7Bb%5E2-4ac%7D%7D%7B2a%7D%24%24)
   

   效果：
   

任務列表

[來自這裡]
在 GitHub 和 GitLab 等網站，除了可以使用有序列表和無序列表外，還可以使用任務列表，很適合要列出一些清單的場景。 原始碼：

**購物清單**

- [ ] 一次性水杯
- [x] 西瓜
- [ ] 豆漿
- [x] 可口可樂
- [ ] 小茗同學

效果：

購物清單

• 一次性水杯
• 西瓜
• 豆漿
• 可口可樂
• 小茗同學

加入 Open Graph 讓你的連結有縮圖

要修改的檔案位置/_includes/meta.html Facebook測試工具、twitter測試工具。我自己的參數設定網站

指定 標題

加入/_includes/meta.html的程式碼：

    
    <meta property="og:title" content="Jekyll 搭建 github page" />
    <meta property="twitter:title" content="Jekyll 搭建 github page" />
    

_posts資料夾底下的md文件的頭部：

---
title: "Jekyll 搭建 github page"
---

指定 簡介

加入/_includes/meta.html的程式碼：

    
    <meta content="手把手用jekyll搭建github靜態網頁" property="og:description">
    

_posts資料夾底下的md文件的頭部：

---
description: "要參與一些大型開源項目，加入IRC是第一步"
---

添加 圖片縮圖

加入/_includes/meta.html的程式碼：

    
    <meta property="og:image" content="https://blog.doge.tgimage/jekyll10.png">
    

_posts資料夾底下的md文件的頭部：

---
image: image/jekyll1.png
---

新增頁面

在我們得到一個現成的模板後，像我就只有Blog,About兩個頁面。 可是要多加幾頁得到如下的效果該怎們辦呢？自己又添加了 閱讀、主題，兩個頁面。

• 首先，在主目錄底下創一個自己高興的.md文件，像我多加了reading.md。ok這樣是不夠的，系統是已經幫
• ok這樣是不夠的，系統是已經幫你創建了頁面，但是你必須要修改一下預設模板，位置在_layouts/default.html，看自己的需求進行排版調整。

            <nav>
            <a href="/">Blog</a>
            <a href="/reading">閱讀</a>
            <a href="/categories">主題</a>
            <a href="/about">About</a>
              
            <!-- <a href="/tags">tags</a> -->
          </nav>
  

添加翻頁功能

• 在主目錄下nano Gemfile，存入以下內容

  group :jekyll_plugins do
    gem "jekyll-paginate"
    gem "jekyll"
  end
  

• 在主目錄下_config.yml文件添加兩行：

  paginate: 7
    paginate_path: "/page:num/"
  

• 跑到主目錄下的 index.html，按照這樣修改
• 執行以下指令：

  gem install jekyll bundler
  bundle add webrick
  bundle install
  bundle exec jekyll serve
  

結束

參考文獻

• 官網連結
• 簡體中文官網
• 关于 Markdown 的一些奇技淫巧
• 讓網頁在 Twitter 推文時顯示圖片 - 在 github pages 中加上 Twitter Cards 與 Open Graph 標籤
• adding-open-graph-tags-to-jekyll.html
• Jekyll and Facebook OG Images

Written on August 31, 2019