Communitygithub.com

imswarnil/Personal-Website-Jekyll-Theme

快速建立基於此 Jekyll 主題的個人網站 — 包含部落格、作品集、影片、網路系列、課程、播客、電子報、旅遊、裝備與履歷 — 並部署到 GitHub Pages 上的 username.github.io。當有人想從此 repo 建立自己的網站、想新增或調整某個內容集合、想更改條目頁面的構成,或是首次部署時使用。

Personal-Website-Jekyll-Theme 是什麼?

這個 Jekyll 主題是一個以數據驅動而非模板驅動的個人網站建構工具,支援部落格、作品集、影片、網路系列、課程、播客、電子報、旅遊、裝備與履歷等多種內容集合。它的核心設計理念是讓使用者能透過調整 `_config.yml` 與在對應資料夾中新增檔案來完成大部分修改,而非編輯版面配置檔。內建互動式設定精靈(`npm run setup`)可安全地引導使用者完成基本設定,並支援 GitHub Actions 自動部署到 GitHub Pages。開發者可以透過設定 `collections` 區塊來新增自訂內容集合,並透過 `single` 區塊的 `parts`、`widgets` 與 `lead` 設定來動態組合每個條目頁面的版面,無需撰寫新的版面配置。此主題也支援標籤頁面自動生成、多種卡片設計,並遵循統一的設計系統,讓開發者能快速建立外觀一致且功能豐富的個人網站。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imswarnil/Personal-Website-Jekyll-Theme/tree/HEAD/.claude/skills/personal-site

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

以此主題為某人建立個人網站

此主題由資料構成,而非模板。幾乎所有使用者要求的變更都是修改 _config.yml 加上在資料夾中放入一個檔案 — 如果你發現自己在編輯版面配置,請先查閱此文件,因為你想要的鉤子可能已經存在。

1. 最快路徑:設定精靈

npm run setup          # 開啟本地表單,寫入 _config.yml,備份被取代的內容

它只綁定到 127.0.0.1,絕不上傳任何資料,並會先將所有被取代的內容複製到 .imprint-backup/<timestamp>/ 中。它會從目前的設定預先填入,因此可以安全地再次執行。

精靈涵蓋身份、強調色、頁首與頁尾、導覽、社交連結、內容集合、廣告、分析、電子報端點與網域。它故意不涵蓋各內容集合的頁面組成 — 它會原封不動地保留這些鍵值(請參閱§4)。

接著:

npm run dev            # http://localhost:4000
npm run check          # 醫生檢查 + 正式編譯

2. 部署到 username.github.io

  1. 建立一個名為 username.github.io 的 repo(一個使用者頁面),或任何名稱作為專案頁面。
  2. 將此目錄樹推送到 main。
  3. 設定 → Pages → 來源:GitHub Actions。

.github/workflows/jekyll.yml 使用 Ruby 3.4 編譯並部署 _site/。它會傳遞 --baseurl "${{ steps.pages.outputs.base_path }}",因此同一個 workflow 對使用者頁面(空基底路徑)和專案頁面(/repo-name/)都正確 — 請勿硬編碼 baseurl。

CNAME 檔案存放自訂網域。若無自訂網域 → 刪除此檔案;當你在精靈中將網域欄位留空時,精靈會自動為你執行此操作。

3. 新增一個內容集合

內容集合是一種內容類型:部落格、作品集、播客、裝備清單。在 _config.yml 的 collections: 下新增一個:

  recipes:
    output: true
    title: Recipes
    singular: Recipe
    description: "關於此集合的一行描述。"
    permalink: /recipes/:name/
    landing: /recipes/
    icon: cooking-pot          # 任何 phosphoricons.com 的名稱
    schema: Recipe             # schema.org 類型,用於 JSON-LD
    card: blog                 # 選擇哪種卡片設計(參閱§5)
    hero: { pattern: dots }    # 著陸頁英雄區域;`hero: false` 為緊湊標題
    image: "/assets/img/covers/recipes.svg"
    single:                    # 條目頁面的組成(參閱§4)
      lead: cover
      parts: [breadcrumbs, head, lead, prose, tags, share, ask, author, nav]
      widgets: [toc, collection, about]

接著:

mkdir _recipes                       # Jekyll 讀取的資料夾
# 一個列出該集合的著陸頁面:
printf -- '---\nlayout: page\ntitle: Recipes\npermalink: /recipes/\nlist_collection: recipes\n---\n' > recipes.html
npm run thumbs                       # 為新集合繪製封面圖

npm run doctor 會告訴你是否遺漏了上述任何步驟。

此主題內建了十三個集合:posts、portfolio、videos、snippets、prompts、webseries + episodes、courses + lessons、podcast、newsletter、travel、uses。子集合(如 episode、lesson)透過 front matter 中的 slug(series: 或 course:)歸屬於其父集合。

4. 更改條目頁面的組成

這部分通常讓人們以為需要新的版面配置,但其實不然。

    single:
      lead: portfolio                 # _includes/leads/portfolio.html
      parts: [breadcrumbs, head, lead, prose, tags, share, ask, comments, author, nav]
      widgets: [details, toc, collection, cta]
      sidebar: true
  • parts → _includes/single/<name>.html,依給定順序堆疊
  • widgets → _includes/widgets/<name>.html,位於側邊欄
  • lead → _includes/leads/<name>.html(設為 none 則無 lead)

透過放入檔案並命名來發明新的部分。 無需編輯任何版面配置。任何單一條目都可以在其自身的 front matter 中覆蓋這三個設定。

內建的部分:breadcrumbs head toc-mobile lead prose tags share ask comments author nav episodes lessons siblings。 小工具:toc details collection about cta share subscribe ad。 Lead:cover video prompt snippet portfolio series audio。

5. 卡片設計

在內容集合上設定 card: <name> 會選取 _includes/cards/<name>.html。內建:blog(編輯風格)、portfolio(repo 卡片)、video(播放器)、snippet(程式碼視窗)、prompt(聊天視窗)、webseries(直式海報)、episode、course、lesson、podcast、issue、trip、product。未設定時預設為 blog,因此新的集合在擁有自己的設計之前仍能正確顯示。

網格行中的卡片高度始終相同。 .im-cards 會拉伸每個項目,而卡片的 body 會佔據剩餘空間 — 因此新的卡片只需在其 body 上設定 flex: 1,並在其底部設定 margin-top: auto。

6. 標籤頁面

_plugins/tag_pages.rb 會為每個標籤在 /tags/<slug>/ 建立一個頁面,範圍涵蓋所有內容集合 — Jekyll 自己的 site.tags 只會看到文章,在一個同時為影片和裝備加上標籤的網站上,這只會顯示出攜帶該標籤內容的三分之一。標籤會根據 slug 分組,因此 Analytics 和 analytics 會被視為同一個主題。

_plugins/ 中的生成器會在我們呼叫 Jekyll 時執行,這正是 .github/workflows/jekyll.yml 所做的事。它在 GitHub 的舊版「從分支編譯」Pages 模式下不會執行;在該模式下,請設定 tag_pages: false,標籤連結會回退到 /tags/ 頁面上的錨點。

7. 設計風格 — 在撰寫 CSS 之前請先閱讀

此主題遵循 Im 設計系統,且它只有兩種互動效果:

  • HOVER — 元素填滿(--im-hover-bg)。不會讓邊框變銳利、不會放大百分之三、也不會依賴陰影。
  • CURRENT — 「你在此處」:較深的填滿與較粗的字體(--im-current-bg/-fg/-weight)。它絕不會改變顏色。

強調色僅用於主要按鈕、連結的懸停效果、焦點環、選取狀態,以及每個內容集合的衍生色調 — 除此之外不用。填滿按鈕與卡片的視覺效果完全相同:恰好升起一個像素,並帶有一條極細的陰影。

所有顏色都使用 --im-* 自訂屬性,沒有任何字面顏色值。_sass/im/abstracts/_mixins.scss 中包含這兩種互動效果的定義,只撰寫一次。

8. 命令列表

npm run setup     # 瀏覽器設定表單
npm run dev       # 本地伺服器 + 即時重新載入
npm run build     # 正式編譯至 _site/
npm run new       # 在任何內容集合中建立新條目
npm run thumbs    # (重)繪製由強調色生成的封面圖
npm run doctor    # 檢查設定中會導致編譯失敗的錯誤
npm run test      # 設定/精靈測試套件
npm run check     # doctor + 編譯,等同於 CI 做的事情

需要 Ruby 3.4(.ruby-version);macOS 系統自帶的 Ruby 2.6 無法編譯此網站。bin/serve 和 bin/build 會強制將正確的工具鏈加入 PATH。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能