利用 Github Pages 免費架一個靜態網頁

Step 0: 靜態網頁 vs. 動態網頁

image

Step 1: 設定自動同步 readme.md & index.md 腳本

這種方式可以 讓你只維護 README.md，然後在每次 Git commit 前，自動產生對應的 index.md 作為 GitHub Pages 的首頁，非常適合開發者使用的 workflow 🚀

✅ 最終效果

每次你 git commit 前，Git 會：

  1. 讀取 README.md
  2. 在前面加上 Jekyll 的 front matter
  3. 輸出成 index.md 給 GitHub Pages 使用

🔧 教學步驟：建立 Git pre-commit hook

📁 步驟 1：建立 .git/hooks/pre-commit 檔案（或修改它）

在你的 repo 根目錄中，打開 terminal：

cd pages-med-utils/.git/hooks
nano pre-commit

或你可以用 VS Code/任何編輯器。

📝 步驟 2：貼上以下腳本內容

#!/bin/bash

# 這是 pre-commit hook，自動從 README.md 生成 index.md（含 Jekyll front matter）

echo "---" > index.md
echo "layout: default" >> index.md
echo "title: Home" >> index.md
echo "---" >> index.md
echo "" >> index.md

cat README.md >> index.md

echo "[pre-commit] index.md has been updated from README.md"

🔁 你可以根據實際需要修改 layout 或其他 front matter。

📛 步驟 3：賦予這個檔案執行權限

🧪 步驟 4：測試一下！

  1. 編輯 README.md
  2. 執行：
git add .
git commit -m "Update README"

你會看到：

[pre-commit] index.md has been updated from README.md

然後 index.md 也自動更新啦 🎉

🔄 額外升級（可選）

如果你要讓這段 hook 能跨機使用或分享給其他人，也可以放到 .githooks/pre-commit 並設一個 core.hooksPath：

mkdir .githooks
mv .git/hooks/pre-commit .githooks/pre-commit
git config core.hooksPath .githooks

Step 2: 讓 markdown 檔案可以顯示在網頁上

簡易版本

---
layout: default
title: Home
---

Step 3: 插入圖片

方法二：用 site.url 和 site.baseurl（比較通用）

.md 或 HTML 裡寫上絕對路徑：

![for loop](/assets/images/tools/flowchart-for-loop.jpeg)

Step 4: 進階設定

1. 新增 RSS 訂閱功能透過加入 jekyll-feed 插件，讓讀者能訂閱你的部落格，獲得最新文章通知

設定方法： 在 _config.yml 中加入：

plugins:
  - jekyll-feed

2. 啟用文章分類與標籤使用 jekyll-archives 插件，將文章依照分類或標籤整理，方便讀者瀏覽特定主題的內容

設定方法： 在 _config.yml 中加入：

plugins:
  - jekyll-archives

3. 新增搜尋功能導入如 Lunr.js 的搜尋功能，讓讀者能快速找到感興趣的文章

4. 建立「關於我」頁面提供一個「關於我」頁面，介紹你的背景、專業領域或部落格的宗旨，增加讀者的信任感

📈 SEO 與社群分享優化

5. *完善 SEO 設定

使用 jekyll-seo-tag 插件，自動生成適當的 meta 標籤，提升搜尋引擎的收錄效。

設定方法： 在 _config.yml 中加入：

plugins:
  - jekyll-seo-tag

並在你的佈局檔案（如 _layouts/default.html）的 <head> 區塊中加：

<!-- Begin Jekyll SEO tag v2.9.0 -->
<title>Github Pages | Ian’s Blog</title>
<meta name="generator" content="Jekyll v4.4.1" />
<meta property="og:title" content="Github Pages" />
<meta property="og:locale" content="en_US" />
<link rel="canonical" href="https://liuyian.uk/en/tools/github_pages/" />
<meta property="og:url" content="https://liuyian.uk/en/tools/github_pages/" />
<meta property="og:site_name" content="Ian’s Blog" />
<meta property="og:type" content="website" />
<meta name="twitter:card" content="summary" />
<meta name="twitter:title" content="Github Pages" />
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"WebPage","headline":"Github Pages","url":"https://liuyian.uk/en/tools/github_pages/"}</script>
<!-- End Jekyll SEO tag -->

6. *新增網站地圖

透過 jekyll-sitemap 插件，自動生成 sitemap.xml，幫助搜尋引擎更有效地索引你的網。

設定方法： 在 _config.yml 中加入：

plugins:
  - jekyll-sitemap

7. *整合社群分享功能

加入社群分享按鈕，讓讀者能輕鬆分享文章至 Facebook、Twitter 等平台，擴大曝光。

🎨 使用者體驗與設計建議

8. *優化行動裝置顯示

確保網站在手機和平板上也有良好的顯示效果。你可以使用 Google 的行動裝置友好測試工具 來檢查並化。

9. *自訂網站風格

透過修改 assets/css/style.scss，自訂網站的配色、字體等風格，讓部落格更具個人色。

📊 進階功能建議

10. 整合網站分析工

使用 Google Analytics 或其他分析工具，了解讀者的瀏覽行為，進一步優化內容佈局。

11. 啟用留言功

透過整合 Disqus 等第三方服務，讓讀者能在文章下方留言，增加動性。

Step 5: 外觀 (加入側邊欄, 程式碼區塊方框)

5.1 加入側邊欄

所有頁面都自動帶有 可折疊的目錄欄（TOC），需要 修改 _layouts/default.html，把 TOC 整合進每一頁的主架構。

5.1.0 最終資料夾結構

IanBlog/
├── _layouts/
│   └── default.html               ← 加入 TOC 結構的主模板
├── assets/
│   ├── css/
│   │   └── style.scss            ← 高亮 TOC 的 CSS
│   ├── js/
│   |   └── main.js               ← tocbot 的初始化腳本
|   └── images/
│
├── index.md                      ← 首頁（含目錄導引）
├── README.md                     ← GitHub repo 說明（可選）
│
├── {文章資料夾1}/
│   └── {文章1}.md
├── {文章資料夾2}/
│   ├── {文章2}.md
└── {文章資料夾3}/
    └── {文章3}.md

5.1.1 新增 _layouts/default.html

這邊是一個 簡潔、通用的 layout 結構，可以讓 TOC 固定在左側、內容在右側，自動作用於所有頁面：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Github Pages</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <link rel="stylesheet" href="/assets/css/style.css">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/tocbot.css">

    <!-- Begin Jekyll SEO tag v2.9.0 -->
<title>Github Pages | Ian’s Blog</title>
<meta name="generator" content="Jekyll v4.4.1" />
<meta property="og:title" content="Github Pages" />
<meta property="og:locale" content="en_US" />
<link rel="canonical" href="https://liuyian.uk/en/tools/github_pages/" />
<meta property="og:url" content="https://liuyian.uk/en/tools/github_pages/" />
<meta property="og:site_name" content="Ian’s Blog" />
<meta property="og:type" content="website" />
<meta name="twitter:card" content="summary" />
<meta name="twitter:title" content="Github Pages" />
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"WebPage","headline":"Github Pages","url":"https://liuyian.uk/en/tools/github_pages/"}</script>
<!-- End Jekyll SEO tag -->
 <!-- 如果有 jekyll-seo-tag -->
  </head>
  <body>
    <div style="display: flex; max-width: 1200px; margin: 0 auto; padding: 1rem;">
      
      <nav class="js-toc" style="width: 250px; margin-right: 2rem; position: sticky; top: 1rem;"></nav>

      <div class="js-toc-content" style="flex: 1;">
        <h1 id="git">Git</h1>

<h2 id="local-repo-connect-to-a-remote-repository">Local Repo Connect to a Remote Repository</h2>
<ul>
  <li><code class="language-plaintext highlighter-rouge">git init</code></li>
  <li><code class="language-plaintext highlighter-rouge">git remote add origin &lt;liink.git&gt;</code></li>
  <li><code class="language-plaintext highlighter-rouge">git remote -v</code></li>
</ul>

<h2 id="first-pull--push-note">First Pull &amp; Push Note</h2>
<ul>
  <li><code class="language-plaintext highlighter-rouge">git pull origin main</code>: Pull latest changes from remote main branch</li>
  <li><code class="language-plaintext highlighter-rouge">git add .</code>: Add all new or changed files</li>
  <li><code class="language-plaintext highlighter-rouge">git commit -m "first commit"</code>: Commit changes with a message</li>
  <li><code class="language-plaintext highlighter-rouge">git branch</code>: Check current branch name</li>
  <li><code class="language-plaintext highlighter-rouge">git push -u origin {branch_name}</code>: Push to remote main branch and set upstream</li>
</ul>

<h2 id="basic-git-workflow-add-commit-and-push">Basic Git Workflow: Add, Commit, and Push</h2>
<ul>
  <li><code class="language-plaintext highlighter-rouge">git add .</code>: Stage all changes in working directory for the next commit.</li>
  <li><code class="language-plaintext highlighter-rouge">git commit -m '&lt;message&gt;'</code>: Save staged changes to the local repository with a descriptive message explaining what this commit does.</li>
  <li><code class="language-plaintext highlighter-rouge">git push</code>: Upload local commits to the remote repository (e.g., GitHub), making changes visible to others.</li>
</ul>

<h2 id="create-and-edit-a-gitignore-file">Create and Edit a <code class="language-plaintext highlighter-rouge">.gitignore</code> File</h2>
<ul>
  <li>(wins) <code class="language-plaintext highlighter-rouge">New-Item -Path . -Name ".gitignore" -ItemType "File" -Force</code></li>
  <li>(linux) <code class="language-plaintext highlighter-rouge">nano .gitignore</code></li>
  <li>(mac)
    <ol>
      <li><code class="language-plaintext highlighter-rouge">touch .gitignore</code>: Create .gitignore file</li>
      <li><code class="language-plaintext highlighter-rouge">nano .gitignore</code>: Edit in terminal</li>
      <li>press <code class="language-plaintext highlighter-rouge">Ctrl + O</code>: Write out</li>
      <li>press <code class="language-plaintext highlighter-rouge">Enter</code>: Check file name correct</li>
      <li>press <code class="language-plaintext highlighter-rouge">Ctrl + x</code>: Exit nano editor</li>
    </ol>
  </li>
</ul>

<h3 id="gitignore-content-example"><code class="language-plaintext highlighter-rouge">.gitignore</code> content example</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># .gitignore</span>
<span class="k">*</span>.tsv
<span class="k">*</span>.geojson
</code></pre></div></div>

<h2 id="remove-a-file-from-tracking-keep-it-locally">Remove a File from Tracking (Keep It Locally)</h2>
<p>Scenario: Already pushed a file to a GitHub repo but now want to remove it from version control - keeping it only on local maching and ignoring it in the future.</p>
<ol>
  <li><code class="language-plaintext highlighter-rouge">git rm --cached {file_name}</code>: Stop tracking the file(but keep it locally).</li>
  <li><code class="language-plaintext highlighter-rouge">echo "{file_name}" &gt;&gt; .gitignore</code>: Add the file to <code class="language-plaintext highlighter-rouge">.gitignore</code> so it’s not tracked again.</li>
  <li><code class="language-plaintext highlighter-rouge">git add .gitignore</code>: Stage the updated <code class="language-plaintext highlighter-rouge">.gitignore</code> file.</li>
  <li><code class="language-plaintext highlighter-rouge">git commit -m "{commit_message}"</code></li>
  <li><code class="language-plaintext highlighter-rouge">git push</code></li>
</ol>

<h2 id="retrieving-a-file-from-an-older-git-commit-without-overwriting-current-version">Retrieving a File from an Older Git Commit (Without Overwriting Current Version)</h2>
<ol>
  <li><strong>Check file history:</strong> <code class="language-plaintext highlighter-rouge">git log -- Multinomial_naive_Bayes/main.py</code> → find the commit hash where the file was modified (e.g. <code class="language-plaintext highlighter-rouge">050e8222</code>).</li>
  <li><strong>Extract old version:</strong> <code class="language-plaintext highlighter-rouge">git show 050e8222:Multinomial_naive_Bayes/main.py &gt; Multinomial_naive_Bayes/main_old.py</code> → save the historical version as <code class="language-plaintext highlighter-rouge">main_old.py</code> without overwriting the current <code class="language-plaintext highlighter-rouge">main.py</code>.</li>
  <li>(Optional) Add and commit the retrieved file: <code class="language-plaintext highlighter-rouge">git commit -m "Add historical version of main.py from commit 050e8222"</code></li>
</ol>

<h2 id="git-branch-management">Git Branch Management</h2>
<ul>
  <li>check current branch name: <code class="language-plaintext highlighter-rouge">git branch</code></li>
  <li>rename current branch locally: <code class="language-plaintext highlighter-rouge">git branch -M {branch name}</code></li>
  <li>delete old branch: <code class="language-plaintext highlighter-rouge">git push origin --delete master</code></li>
  <li>verify everthing: <code class="language-plaintext highlighter-rouge">git branch -a</code></li>
  <li>切換到新分支:<code class="language-plaintext highlighter-rouge">git checkout experiment</code></li>
</ul>

<h2 id="force-pull-from-a-git-remote-repository--discard-all-local-changes">Force pull from a Git remote repository &amp; discard all local changes</h2>

<p>To <strong>force pull from a Git remote repository</strong> and <strong>discard all local changes</strong>, follow these steps carefully. This will overwrite your local files and history with the latest from the remote, <strong>so make sure you’re okay with losing any uncommitted local work</strong>.</p>

<h2 id="compare-difference">Compare difference</h2>
<ul>
  <li><code class="language-plaintext highlighter-rouge">git diff --color-words {commit 版號開頭 1} {commit 版號開頭 2} -- {file}</code></li>
  <li>Example: <code class="language-plaintext highlighter-rouge">git diff --color-words 6d8d2361 7218ae5a3 -- ./Hofn.py</code></li>
</ul>

<hr />

<h3 id="-warning">🚨 WARNING:</h3>

<p>This process will <strong>delete all local changes</strong>, including uncommitted and committed but not pushed changes.</p>

<hr />

<h2 id="-steps-to-force-pull-and-recover-remote-repository">✅ Steps to Force Pull and Recover Remote Repository:</h2>

<h3 id="1-discard-uncommitted-changes-optional-but-recommended-if-youre-unsure"><strong>1. Discard uncommitted changes (optional but recommended if you’re unsure):</strong></h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git reset <span class="nt">--hard</span>
git clean <span class="nt">-fd</span>
</code></pre></div></div>

<ul>
  <li><code class="language-plaintext highlighter-rouge">reset --hard</code>: resets tracked files to the last commit</li>
  <li><code class="language-plaintext highlighter-rouge">clean -fd</code>: removes untracked files and directories</li>
</ul>

<hr />

<h3 id="2-fetch-latest-remote-data"><strong>2. Fetch latest remote data:</strong></h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git fetch <span class="nt">--all</span>
</code></pre></div></div>

<h2 id="ssh--personal-access-token">SSH &amp; Personal Access Token</h2>
<ul>
  <li>Personal Access Token 要用 https 的網址 clone</li>
  <li>SSH 要用 ssh 的網址 clone</li>
</ul>

<h3 id="1-使用-https--personal-access-token建議">1. 使用 HTTPS + Personal Access Token（建議）</h3>

<p>如果你的 GitLab 是透過 HTTPS 存取（網址開頭為 <code class="language-plaintext highlighter-rouge">https://</code>），你需要在 clone 時提供：</p>

<ul>
  <li><strong>帳號（Username）</strong></li>
  <li><strong>個人存取權杖（Personal Access Token）</strong> → 取代密碼使用</li>
</ul>

<h4 id="-步驟">🔧 步驟：</h4>

<ol>
  <li>登入 GitLab 網站 → 點右上角頭像 → <code class="language-plaintext highlighter-rouge">Edit Profile</code> → <code class="language-plaintext highlighter-rouge">Access Tokens</code> 或 <code class="language-plaintext highlighter-rouge">Personal Access Tokens</code></li>
  <li>建立一組 Token，至少包含：
    <ul>
      <li><code class="language-plaintext highlighter-rouge">read_repository</code></li>
      <li><code class="language-plaintext highlighter-rouge">write_repository</code>（如果有 push 需求）</li>
    </ul>
  </li>
  <li>使用指令 clone：
    <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone https://gitlab.company.com/your_group/your_repo.git
</code></pre></div>    </div>
  </li>
  <li>系統會提示輸入帳號與密碼：
    <ul>
      <li><strong>Username</strong> → 你的 GitLab 帳號</li>
      <li><strong>Password</strong> → 剛剛建立的 Token</li>
    </ul>
  </li>
</ol>

<blockquote>
  <p>💡 可將 Token 儲存在 Git Credential Manager 或 <code class="language-plaintext highlighter-rouge">.netrc</code> 中，避免每次輸入。</p>
</blockquote>

<hr />

<h3 id="2-使用-ssh-金鑰最方便">2. 使用 SSH 金鑰（最方便）</h3>

<p>如果你公司允許使用 SSH，你可以設定 SSH 金鑰來避免每次輸入密碼。</p>

<h4 id="-步驟-1">🔧 步驟：</h4>

<ol>
  <li>在本機產生 SSH 金鑰（如果還沒有）：
    <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ssh-keygen <span class="nt">-t</span> ed25519 <span class="nt">-C</span> <span class="s2">"[email protected]"</span>
</code></pre></div>    </div>
    <blockquote>
      <p>預設儲存於 <code class="language-plaintext highlighter-rouge">~/.ssh/id_ed25519</code></p>
    </blockquote>
  </li>
  <li>查看公開金鑰內容：
    <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cat</span> ~/.ssh/id_ed25519.pub
</code></pre></div>    </div>
  </li>
  <li>登入 GitLab，新增金鑰：
    <ul>
      <li><code class="language-plaintext highlighter-rouge">Edit Profile</code> → <code class="language-plaintext highlighter-rouge">SSH Keys</code> → 貼上 <code class="language-plaintext highlighter-rouge">id_ed25519.pub</code> 的內容</li>
    </ul>
  </li>
  <li>使用 SSH 方式 clone：
    <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone [email protected]:your_group/your_repo.git
</code></pre></div>    </div>
  </li>
</ol>

<blockquote>
  <p>💡 第一次 clone 可能會提示確認主機指紋，輸入 <code class="language-plaintext highlighter-rouge">yes</code> 以信任該主機。</p>
</blockquote>

<h3 id="-一檢查現有-ssh-金鑰">✅ 一、檢查現有 SSH 金鑰</h3>

<p>打開終端機（Terminal）後，輸入以下指令：</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">ls</span> ~/.ssh
</code></pre></div></div>

<h4 id="常見的金鑰檔案名稱">常見的金鑰檔案名稱：</h4>

<table>
  <thead>
    <tr>
      <th>檔案名稱</th>
      <th>說明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code class="language-plaintext highlighter-rouge">id_rsa</code></td>
      <td>傳統 RSA 私鑰</td>
    </tr>
    <tr>
      <td><code class="language-plaintext highlighter-rouge">id_rsa.pub</code></td>
      <td>對應的公鑰</td>
    </tr>
    <tr>
      <td><code class="language-plaintext highlighter-rouge">id_ed25519</code></td>
      <td>較新、建議使用的 ED25519 私鑰</td>
    </tr>
    <tr>
      <td><code class="language-plaintext highlighter-rouge">id_ed25519.pub</code></td>
      <td>對應的公鑰</td>
    </tr>
    <tr>
      <td><code class="language-plaintext highlighter-rouge">known_hosts</code></td>
      <td>連過的主機指紋</td>
    </tr>
    <tr>
      <td><code class="language-plaintext highlighter-rouge">config</code></td>
      <td>SSH 設定檔</td>
    </tr>
  </tbody>
</table>

<h3 id="-二查看特定公鑰內容你要貼到-gitlab-的">✅ 二、查看特定公鑰內容（你要貼到 GitLab 的）</h3>

<p>如果你看到像是 <code class="language-plaintext highlighter-rouge">id_ed25519.pub</code> 或 <code class="language-plaintext highlighter-rouge">id_rsa.pub</code>，可以用以下指令查看內容：</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cat</span> ~/.ssh/id_ed25519.pub
</code></pre></div></div>

<p>或</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cat</span> ~/.ssh/id_rsa.pub
</code></pre></div></div>

<blockquote>
  <p><strong>提示</strong>：輸出的內容是你要複製並貼到 GitLab SSH Keys 頁面的公鑰文字。</p>
</blockquote>

<h3 id="-查看曾經連過的-ssh-主機列表">🧾 查看曾經連過的 SSH 主機列表</h3>

<p>你可以透過查看 <code class="language-plaintext highlighter-rouge">~/.ssh/known_hosts</code> 檔案來列出曾經使用 SSH 連線過的主機。</p>

<h4 id="-指令">✅ 指令</h4>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cut</span> <span class="nt">-f1</span> <span class="nt">-d</span><span class="s1">' '</span> ~/.ssh/known_hosts | <span class="nb">sed</span> <span class="s1">'s/,.*//'</span>
</code></pre></div></div>

<h4 id="-指令說明">🔍 指令說明</h4>

<ul>
  <li>
    <p><code class="language-plaintext highlighter-rouge">cut -f1 -d' '</code>
➤ 取得每行空格前的第一欄（通常是主機名稱或 IP）</p>
  </li>
  <li>
    <p><code class="language-plaintext highlighter-rouge">sed 's/,.*//'</code>
➤ 去掉逗號後面的內容（處理多個主機名的情況，只保留主要主機名）</p>
  </li>
</ul>

<h2 id="note">Note</h2>
<ul>
  <li>commit 階段 如果只下 <code class="language-plaintext highlighter-rouge">git commit</code> + <code class="language-plaintext highlighter-rouge">enter</code> 可以進入預設的編輯器，這樣就可以一次commit多行</li>
  <li>
    <p>asic Vim commands in this context</p>

    <table>
      <thead>
        <tr>
          <th>Action</th>
          <th>Command</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Enter insert mode</td>
          <td><code class="language-plaintext highlighter-rouge">i</code></td>
        </tr>
        <tr>
          <td>Exit insert mode</td>
          <td><code class="language-plaintext highlighter-rouge">Esc</code></td>
        </tr>
        <tr>
          <td>Save &amp; quit editor</td>
          <td><code class="language-plaintext highlighter-rouge">:wq</code> + Enter</td>
        </tr>
        <tr>
          <td>Quit without save</td>
          <td><code class="language-plaintext highlighter-rouge">:q!</code> + Enter</td>
        </tr>
        <tr>
          <td>Move cursor</td>
          <td>Arrow keys</td>
        </tr>
      </tbody>
    </table>
  </li>
</ul>

      </div>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/tocbot.min.js"></script> <!-- TOC Script -->
    <script src="/assets/js/main.js"></script>   <!-- custom script -->

  </body>
</html>

Note:

5.1.2 新增 assets/css/style.scss

這樣可以讓目前閱讀區塊的目錄高亮顯示：

.is-active-link {
  font-weight: bold;
  color: #1a73e8;
}

5.1.3 新增 assets/js/main.js

tocbot.init({
  tocSelector: '.js-toc',
  contentSelector: '.js-toc-content',
  headingSelector: 'h1, h2, h3, h4, h5, h6',
  collapseDepth: 6,
  scrollSmooth: true,
  orderedList: false,
});

5.1.4 最後檢查一下每個 .md 頁面都要有：


---
layout: default
title: 任意標題
---

這樣才能套用我們剛剛改的 default.html！

5.2 解決插入sidebar後圖片變超大

img {
    max-width: 100%;
    height: auto;
    display: block;
    margin: 1rem auto;
}

5.3 加入區塊程式碼方框(markdown)

/* Style for code blocks (surrounded by triple backticks ```) */
pre {
  background: #f5f5f5;       /* Light gray background */
  border: 1px solid #ccc;    /* Gray border */
  border-radius: 6px;
  padding: 1rem;
  overflow-x: auto;          /* Enable horizontal scroll for overflow */
  font-family: Consolas, Monaco, 'Courier New', monospace;
  font-size: 0.95rem;
  line-height: 1.5;
}

/* Additional styling for code content */
code {
  font-family: Consolas, Monaco, 'Courier New', monospace;
  font-size: 0.95rem;
  color: #333;
}

/* Inline code styling (e.g. `example`) */
p code, li code {
  background-color: #eee;
  padding: 0.2em 0.4em;
  border-radius: 3px;
  font-size: 0.9em;
}

5.4 使的側邊欄可收合

要讓你的 TOC 側邊欄可收合（可展開 / 收起），我們可以加上一些簡單的 JavaScript 搭配 CSS 切換 class，以下是完整解法：

✅ 修改後的內容包括：

  1. 為側邊欄加上 切換按鈕
  2. 增加 .collapsed class 的 CSS 控制樣式
  3. 加入 JavaScript 處理「收合 / 展開」行為

5.4.1 修改 default.html

在 <nav class="sidebar js-toc"> 外面包一個容器，加上一個按鈕：

<!-- TOC 導覽欄容器 -->
<div class="sidebar-wrapper">
  <button id="toggle-sidebar">☰ Table of Contents</button>
  <nav class="sidebar js-toc"></nav>
</div>

main.js 改為：

<script>
  // 初始化 TOCBOT
  tocbot.init({
    tocSelector: '.js-toc',
    contentSelector: '.js-toc-content',
    headingSelector: 'h1, h2, h3, h4, h5, h6',
    collapseDepth: 6,
    scrollSmooth: true,
    orderedList: false,
  });

  // 切換側邊欄顯示 / 隱藏
  document.getElementById('toggle-sidebar').addEventListener('click', function () {
    document.querySelector('.sidebar').classList.toggle('collapsed');
  });
</script>

🎨 修改 style.css

/* 包住 sidebar 與切換按鈕的外框 */
.sidebar-wrapper {
    display: flex;
    flex-direction: column;
    margin-right: 2rem;
    position: sticky;
    top: 1rem;
    align-self: flex-start;
}

/* 收合狀態下隱藏 TOC */
.sidebar.collapsed {
    display: none;
}

/* TOC 切換按鈕 */
#toggle-sidebar {
    background: #eee;
    border: 1px solid #ccc;
    padding: 0.5rem 1rem;
    margin-bottom: 0.5rem;
    border-radius: 4px;
    cursor: pointer;
    font-size: 1rem;
    text-align: left;
}

@media (max-width: 768px) {
    #toggle-sidebar {
    width: 100%;
    }
}

5.5 處理手機板TOC排版

/* Responsive */
@media (max-width: 768px) {
    .container {
        flex-direction: column;
        padding: 0.5rem;
    }

    .sidebar-wrapper {
        width: 100%;
        margin-right: 0;
        position: relative;
    }

    .sidebar {
        width: 100%;
        max-height: 60vh;
        overflow-y: auto;
        background: #fff;
        border: 1px solid #ccc;
        border-radius: 6px;
        box-shadow: 0 2px 6px rgba(0,0,0,0.1);
        margin-bottom: 1rem;
        padding: 1rem;
        z-index: 1;
    }

    .sidebar.collapsed {
        max-height: 0;
        overflow: hidden;
        padding: 0;
        border: none;
        box-shadow: none;
    }

    #toggle-sidebar {
        width: 100%;
        margin-bottom: 0.5rem;
        position: relative;
        z-index: 2;
        background: #f9f9f9;
        font-weight: bold;
    }

    .content {
        z-index: 0;
        position: relative;
    }
}

5.6 程式碼高亮

  1. 新增 assets/rouge.css
  2. 貼上 https://raw.githubusercontent.com/jwarby/jekyll-pygments-themes/master/github.css 內容
  3. 加入到 _layouts/default.html <body> 部分
<script src="/assets/js/main.js"></script>   <!-- custom script -->

5.7 加入 back to home & jump to top

  1. style.css加入
/* Back to home 連結 */
.back-home-link {
    position: fixed;
    bottom: 2rem;
    left: 1.5rem;
    background: #f0f0f0;
    color: #333;
    padding: 0.5rem 1rem;
    text-decoration: none;
    border: 1px solid #ccc;
    border-radius: 4px;
    z-index: 999;
    font-size: 0.9rem;
}


/* TOC 切換按鈕 */
#toggle-sidebar {
    background: #eee;
    border: 1px solid #ccc;
    padding: 0.5rem 1rem;
    margin-bottom: 0.5rem;
    border-radius: 4px;
    cursor: pointer;
    font-size: 1rem;
    text-align: left;
}
  1. main.js 改為
document.addEventListener("DOMContentLoaded", function () {
    // 初始化 tocbot
    tocbot.init({
        tocSelector: '.js-toc',
        contentSelector: '.js-toc-content',
        headingSelector: 'h1, h2, h3, h4, h5, h6',
        hasInnerContainers: true,
        collapseDepth: 6,
        scrollSmooth: true,
        orderedList: false,
    });

    // 切換 TOC 側邊欄顯示
    const toggleButton = document.getElementById("toggle-sidebar");
    const sidebar = document.querySelector(".sidebar");

    toggleButton.addEventListener("click", function () {
        sidebar.classList.toggle("collapsed");
    });

    // Jump to top 功能
    const toTopBtn = document.createElement("button");
    toTopBtn.textContent = "↑ Top";
    toTopBtn.className = "jump-top-btn";
    document.body.appendChild(toTopBtn);

    toTopBtn.addEventListener("click", function () {
        window.scrollTo({ top: 0, behavior: "smooth" });
    });

    // Back to home 功能（只有在不是首頁時顯示）
    if (window.location.pathname !== "//" && window.location.pathname !== "//index.html") {
        const backHomeLink = document.createElement("a");
        backHomeLink.textContent = "← Home";
        backHomeLink.href = "https://liuyian.uk/";
        backHomeLink.className = "back-home-link";
        document.body.appendChild(backHomeLink);
    }
    // 捲動到一定高度後顯示「Top」按鈕
    window.addEventListener("scroll", function () {
        if (window.scrollY > 300) {
            toTopBtn.style.display = "block";
        } else {
            toTopBtn.style.display = "none";
        }
    });
});

5.8 加入navbar

5.8.1 assets/css/style.css 加入

.navbar {
    display: flex;
    justify-content: center;  /* 中置連結群 */
    flex-wrap: wrap;          /* 可自動換行 */
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    background: #fff;
    border-bottom: 1px solid #ddd;
    padding: 0.5rem 1.5rem;
    z-index: 1000;
    font-family: "Segoe UI", sans-serif;
}

.nav-links {
    display: flex;
    flex-wrap: wrap;
    justify-content: center;
}

.nav-links a {
    margin: 0 0.5rem;
    white-space: nowrap; /* 防止換行 */
}

.nav-links a:hover {
    color: #007acc;
}

5.8.2 _layouts/default.html body 部分加入

<nav class="navbar">
    <div class="nav-links">
        <a href="https://liuyian.uk/">Home</a>
        <a href="https://liuyian.uk/tools/">Tools</a>
        <a href="https://liuyian.uk/notes/">Notes</a>
        <a href="https://liuyian.uk/blog/">Blog</a>
        <a href="https://liuyian.uk/about/">About</a>
    </div>
</nav>

5.8 TOC 客製化自動捲動方式　

TODO

Note - debug

如果 deployment 卡住

git commit --amend --no-edit
git push origin main --force

所有事項checklist

已完成

TODO