以此主題為某人建立個人網站
此主題由資料構成,而非模板。幾乎所有使用者要求的變更都是修改 _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
- 建立一個名為
username.github.io的 repo(一個使用者頁面),或任何名稱作為專案頁面。 - 將此目錄樹推送到
main。 - 設定 → 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。