Communitygithub.com

imswarnil/Personal-Website-Jekyll-Theme

快速搭建基于此Jekyll主题的个人网站——博客、作品集、视频、系列课、播客、新闻通讯、旅行、装备和简历——并部署到 GitHub Pages 的 username.github.io。适用于希望从该仓库创建个人网站、添加或调整内容集合、更改条目页面构成,或首次部署的用户。

Personal-Website-Jekyll-Theme 是什么?

这是一个基于 Jekyll 的现代个人网站主题,完全采用数据驱动而非模板驱动,使几乎所有修改只需调整 `_config.yml` 并添加文件即可完成,无需编辑布局文件。它内置了一个交互式设置向导(`npm run setup`),可安全地管理身份、配色、导航、社交媒体链接、集合、广告、分析等配置,并支持自动备份。该主题支持博客、作品集、视频、播客、新闻通讯、旅行等多种内容集合,并提供了灵活的单条目页面构成机制——通过 `parts`、`widgets` 和 `lead` 字段组合不同组件,无需编写布局。此外,它还包含自动标签页面生成器、统一的设计系统(遵循 `--im-*` 自定义属性)和一套完整的开发命令(`dev`、`build`、`doctor`、`check` 等),可部署到 GitHub Pages(用户页或项目页)。该主题强调可维护性和一致性,适合希望快速搭建个性化网站且不熟悉 Jekyll 布局的开发者。

兼容平台~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 的仓库(用户页面),或任何名称的项目页面。
  2. 将该代码树推送到 main 分支。
  3. 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。

Individual skills in this repo

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

相关技能