用此主题为他人搭建个人网站
该主题由数据驱动,而非模板驱动。用户提出的几乎每个修改都是对 _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的仓库(用户页面),或任何名称的项目页面。 - 将该代码树推送到
main分支。 - Settings → Pages → Source:选择 GitHub Actions。
.github/workflows/jekyll.yml 使用 Ruby 3.4 构建并部署 _site/。它会传递 --baseurl "${{ steps.pages.outputs.base_path }}",因此同一个工作流适用于用户页面(空 base 路径)和项目页面(/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 中的 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(仓库卡片)、video(播放器)、snippet(代码窗口)、prompt(聊天窗口)、webseries(肖像海报)、episode、course、lesson、podcast、issue、trip、product。未设置时默认为 blog,因此新集合在拥有自己的设计之前看起来也是正常的。
网格行中的卡片始终等高。 .im-cards 会拉伸每个项目,且卡片的主体部分会填充剩余空间——因此新卡片只需在其主体上设置 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 + build,即 CI 执行的流程
需要 Ruby 3.4(见 .ruby-version);macOS 系统自带的 Ruby 2.6 无法构建此站点。bin/serve 和 bin/build 会强制将正确的工具链加入 PATH。