自定义

项目自带的默认值位于 website/_config.yml。宿主仓库应把覆盖值写入由 website/bin/integrate 生成的 .github/jekyll-obsidian.yml，以便日后替换 website/。最终生效的公开配置仍可在一个文件中审阅：

title: My Site
description: Built from Markdown
lang: en
url: ""
baseurl: ""

website:
  # jekyll-obsidian:managed-start
  source: docs
  theme: minimal
  # jekyll-obsidian:managed-end
  syntax_profile: ofm@1
  repository: owner/repository
  edit_branch: main
  content:
    publish_by_default: []
    default_type: doc
    directories:
      post: []
      doc: []
  features: {}
  contacts:
    - label: GitHub
      url: https://github.com/owner
    - label: Email
      url: mailto:hello@example.com

website.source 相对于宿主仓库根目录。项目自带的默认配置使用 source: website/docs，生成的宿主覆盖通常使用 source: docs，或 website/ 之外的其他目录。

规范命令会依次合并 website/_config.yml、.github/jekyll-obsidian.yml，以及临时命令行值或 Pages 值。集成命令只管理宿主文件中标记之间的 source 和 theme；标题、仓库链接、内容分类和功能覆盖仍可在标记外编辑。bin/build 会把 Jekyll source、实现目录、缓存、目标目录和安全设置固定在 website/。直接运行 jekyll 不会载入宿主覆盖或这些归属保护，因此不是受支持的入口。

website.theme 用于选择 minimal 或 docs。website.syntax_profile 固定 Markdown 契约，目前只接受 ofm@1。website.edit_branch 决定 Edit 与其他宿主源码链接所用的分支，默认值为 main。

发布默认值

website.content.publish_by_default 是一个目录数组，其中的路径相对于 website.source。每个条目会选择该目录及其后代中的 Markdown 文件。默认数组为空，因此笔记必须通过 publish: true 明确加入。如果除显式排除的笔记外，整个内容树都应发布，可以使用 .：

website:
  content:
    publish_by_default:
      - .

显式 YAML 布尔值始终优先。publish: false 会从已选择目录中排除一篇笔记，publish: true 则可以加入目录范围外的一篇笔记。发布目录不会决定内容分类；已发布笔记是页面、文章还是文档，仍由 default_type、directories.post、directories.doc 和笔记的 content_type 决定。附件只有在已发布笔记、其 image 属性或嵌入闭包引用时才会公开。

站点信息

title、description 和 lang 会进入站点外壳、元数据、Atom 和无障碍标签。将 website.repository 设为 owner/repository 可以显示 Edit 链接。该值为空时，构建会检查 GITHUB_REPOSITORY 和本地 origin remote。无法识别仓库时，操作会保持隐藏。这个宿主仓库配置不会更改页脚中的 Built by Jekyll Obsidian 链接；页脚始终指向官方项目 https://github.com/wowfun/jekyll-obsidian。

Minimal Home 会先显示公开的根目录索引，再用编辑式列表显示最近六篇文章。索引默认为 index.md；物理 index.md 不存在时，才会使用同级且文件名精确为 README.md 的公开笔记。被选中的目录索引没有正文一级标题时，不会再通过文件名或 frontmatter 标题补出可见标题；解析后的标题仍用于元数据和导航。带图片的条目在宽屏中把 16:9 缩略图放在摘要旁边，在窄屏中放到摘要上方；没有图片的条目会占满宽度，不显示占位图。摘要还可以显示 subtitle、正文摘录、作者和发布日期。Blog 链接会打开 /blog/ 中完整的倒序文章列表。

配置 website.contacts 后，可以在最近文章区之后显示联系方式。每个条目都需要简短的 label，以及采用 https:、mailto: 或 tel: 的 URL。基础配置没有联系方式时，可以省略该项或使用空数组。Email、Phone、GitHub、LinkedIn、X/Twitter、Mastodon、Bluesky、Instagram、YouTube、Telegram、RSS 和 Website 链接会自动获得无障碍图标。其他服务会直接显示文本标签，因此配置保持服务中立，不需要额外的 icon 字段。

站点主题

每次构建会选择一个完整展示方案。minimal 在通用站点外壳中提供 Home、Blog、Docs 和自定义栏目，docs 则提供专注的分层手册。两个主题共享 Search、Wiki 链接预览、页面大纲、笔记关系和交互式图谱。可以用命令行覆盖配置，在不修改文件的情况下比较同一份内容：

website/bin/dev --theme docs
website/bin/build --theme minimal --url https://example.test --baseurl "" --destination _site

构建会把指定目标写入 website/ 下，因此 _site 实际为 website/_site。主题标识只支持 minimal 和 docs。

website.features 中省略的功能会继承主题默认值。可以用显式 YAML 布尔值覆盖 search、tags、feed、graph、relations、previews 和 outline。

功能	Minimal	Docs
search、previews、outline、relations、graph	开启	开启
tags、feed	开启	关闭

将任意共享功能设为 YAML 布尔值 false 即可移除。例如：

website:
  features:
    graph: false
    previews: false

Minimal 导航

Minimal 默认提供 Home、Blog、Docs 和 Portfolio，顺序分别为 0、10、20 和 30。内容树中没有公开文章或文档时，Blog 与 Docs 会自动消失。Portfolio 默认使用相对于内容根目录的 portfolio 文件夹；其中存在至少一个可见的已发布项目时才会显示。空文件夹或只有未发布内容的文件夹不会增加标签页。可以在 website.navigation 中覆盖内置标签、顺序、可见性或作品集路径：

website:
  theme: minimal
  navigation:
    home:
      label: Home
      order: 0
      visible: true
    blog:
      label: Writing
      order: 10
      visible: true
    docs:
      label: Handbook
      order: 20
      visible: true
    portfolio:
      path: work
      label: Work
      order: 30
      visible: true

作品集路径相对于 website.source；显式路径会取代默认的 portfolio。该路径下的已发布 Markdown 后代统一变成作品集页面，因此其中显式设置的 content_type 必须为 page。公开的目录索引会在项目网格上方保留自定义介绍。可以使用 <path>/index.md；没有物理索引时，也可以使用 <path>/README.md。选中的索引未发布时，编译器会在该路由生成作品集索引。索引本身不算项目。设置了 pinned: true 的项目排在最前；置顶组和普通组内部再依次按 nav_order、标题和路径排序。项目设置 nav_exclude: true 后不会显示卡片；设置 website.navigation.portfolio.visible: false 只会隐藏标签页，作品集索引和项目页面仍然公开。

项目卡片使用 image、标题和 description；未设置描述时，会回退到正文预览。本地 GIF、WebP、AVIF 与 APNG 文件会逐字节复制并通过 <img> 显示，从而保留动画。编译器不会转码或生成缩略图。

项目可以通过 github_markdown 将本地正文替换为公开的 GitHub Markdown 文件。本地项目页继续管理卡片元数据和路由，解析后的远程正文则用于详情页、大纲、Search 文本、预览和 Markdown 端点。接受的 URL 与映射格式、空正文规则、分支刷新、内容上限、相对 URL、本地化和安全边界详见 作品集。

自定义标签页

Minimal 与 Docs 使用同一套自定义标签页契约。在已发布的文件夹索引上声明标签页，可以使用 index.md，也可以使用符合条件的 README.md 回退。该笔记仍是标签页的 canonical 主页，其正文显示在自动生成的成员卡片之前：

---
publish: true
content_type: page
tab:
  id: favorites
  label: 收藏
  order: 40
  topics:
    - favorite
    - reference
---

id 必填，并且必须是 favorites、team-work 这类小写 ASCII 标识符；home、blog、docs 和 portfolio 已保留。标签默认使用本地化后的索引标题，顺序默认为 100。自定义标签页始终可见。其根必须是可见的 content_type: page 文件夹索引，且不能位于当前 Portfolio 路径内。

成员取三类来源的并集：标签页文件夹下所有已发布后代、通过 tabs 指定该标签页的已发布笔记，以及 tags 或 categories 与标签页任一 topics 匹配的已发布笔记。多个 topic 使用 OR 关系，并在 Unicode 规范化和大小写折叠后精确匹配。文件夹外的页面可在不改变路由的情况下加入：

---
publish: true
tabs:
  - favorites
---

成员关系只用于额外展示：文章仍在 Blog 下激活，文档仍在 Docs 下激活，作品集页面仍在 Portfolio 下激活。只有普通页面后代会激活自定义标签页；存在嵌套根时，以最深层根为准。卡片会去重，并依次按 pinned、nav_order、本地化标题和源路径排序。nav_exclude: true 会移除文件夹或 topic 匹配结果，且不能与 tabs 同时使用。topic 没有匹配项是有效状态，此时只显示索引正文。

ID、标签或目标重复，tabs 引用未知标签页，根无效或与保留项冲突，都会让构建失败。即使一个页面加入多个标签页，它也只保留一个 canonical URL；自定义标签页不会创建重定向，也不会在 Search、订阅源或 sitemap 中复制页面。

桌面标题栏放不下的标签页会进入无障碍 More 菜单。移动端 Browse 面板和 Search 对话框的快速导航会复用同一组有序目标和激活状态。Search 会按配置标签筛选快速链接，同时查询笔记正文。没有 JavaScript 时，标题栏链接仍然可见，并会自然换行。从 Minimal 打开 Docs 时会保留 Minimal 站点外壳，同时加入手册目录、页面大纲及上一篇或下一篇链接。

图谱与 Wiki 链接预览

已发布笔记只有在当前语言分区中与另一篇公开笔记存在链接、嵌入、反向链接或反向嵌入时，才会在右侧上下文栏的大纲与关系上方显示一跳图谱。图谱包含当前笔记及这些直接邻居。孤立笔记和仅包含自链的笔记不会显示局部图谱，但完整图谱仍会包含它们。节点面积会随其在完整公开图谱中的度数增加。

图谱左侧按钮打开完整图谱，右侧按钮放大当前笔记的局部图谱。在任一视图中，都可以在画布上滚动鼠标滚轮，以指针为中心缩放；拖动空白画布可以平移；拖动相邻节点可以改变位置。当前节点始终固定在视觉中心。单击节点可以访问对应笔记；键盘聚焦后按 Enter 或 Space 也可以打开。完整图谱 JSON 只在打开对话框时载入，并始终包含全部公开节点与关系。为了保持响应速度，SVG 查看器不会渲染超过 250 个节点或 1,000 条关系的完整图谱，而会提示读者使用局部图谱或 Search。站点不会生成 /graph/ 页面或导航标签，因此已发布笔记可以使用该路由。

鼠标在 Wiki 链接上停留 0.3 秒，或使用键盘聚焦链接时，会打开阅读预览。在延迟结束前移出指针会取消预览；键盘聚焦仍会立即打开。预览先显示目录元数据，再以较小的可见高度显示目标笔记经过清理且可独立滚动的正文。点击预览标题可以进入目标笔记；正文中的链接仍只显示为文本。触摸屏点击原 Wiki 链接会直接进入目标页面。设置 previews: false 可以关闭该行为。

GitHub Discussions 评论

两个主题都可以通过 Giscus 为每篇 content_type: post 关联 GitHub Discussion。未配置 website.comments 时，评论保持关闭。该映射存在但省略 enabled 时，Minimal 默认开启，Docs 默认关闭。首先需要准备一个公开 GitHub 仓库：

1. 打开 Settings → General → Features → Discussions。
2. 创建 Blog comments 分类。建议使用 Announcement 格式，维护者和 Giscus 可以创建讨论，访客仍可回复。
3. 为该仓库安装 Giscus GitHub App。
4. 在 giscus.app 中填写仓库和分类，并复制生成的 ID。

随后把这些值加入宿主配置：

website:
  theme: minimal
  repository: owner/site
  comments:
    # 可选。省略后复用 website.repository。
    repository: owner/community
    repository_id: R_kgDOxxxxxxxx
    category: Blog comments
    category_id: DIC_kwDOxxxxxxxx

Docs 主题需要在 comments 中添加 enabled: true；如果只想保留 Minimal 配置但暂不启用，请添加 enabled: false。评论仓库可以是发布仓库，也可以是独立的公开社区仓库。构建不会检查 Discussions 是否启用或 Giscus App 是否安装。服务 ID 不完整时，构建会产生警告，并显示不可交互的降级内容，不会直接失败。需要把嵌入限制在生产站点来源时，可以在评论仓库中添加 giscus.json。

启用后，任意主题中的每篇 content_type: post 都会显示评论。可以用 YAML 布尔值关闭单篇文章：

---
publish: true
content_type: post
comments: false
---

讨论串使用由笔记路径生成的严格标识，不依赖路由。更改域名、baseurl 或 permalink 不会更换讨论串；移动或重命名源笔记则会产生新的标识。站点启用表情回应，输入框显示在现有评论上方，Giscus iframe 在评论区域接近视口时延迟载入。Giscus 客户端仍会在已发布评论页初始化时发出请求。

本地开发不会连接 Giscus，而会显示仅限发布站点的提示和普通 Discussions 链接。已发布站点和 CI 构建会载入组件，使其跟随站点浅色或深色配色，并在 JavaScript 或外部服务不可用时保留 GitHub 链接。本地化页面共享文章的路由无关讨论串；Giscus 支持该页面语言时使用相应界面，否则回退到英文。

讨论串标识、来源限制、隐私边界和问题排查详见 使用 GitHub Discussions 提供评论。

流量统计

未配置 website.analytics 时，流量统计保持关闭。生产站点可以选择 Cloudflare Web Analytics：

website:
  analytics:
    provider: cloudflare
    token: SITE_TOKEN

也可以选择一个 Google Analytics 4 属性：

website:
  analytics:
    provider: google
    measurement_id: G-XXXXXXXXXX

一个站点只能启用一家服务。本地开发和重定向页面不会载入统计客户端。website/bin/integrate 会保留已有映射，但不会主动创建。服务配置、Docs 导航跟踪、内容安全策略来源、隐私差异和问题排查详见 流量统计。

本地化

两个主题都可以通过 website.i18n 中的语言列表启用静态本地化。该映射存在时，Docs 默认启用，Minimal 默认关闭，需要显式设置 enabled: true。顶层 lang 是默认语言；本地化启用时，它必须出现在列表中：

lang: en

website:
  theme: docs
  i18n:
    locales:
      - en
      - zh-CN

Minimal 需要在 i18n 下添加 enabled: true；Docs 可以通过 enabled: false 暂停已经配置的语言方案。默认语言保留在普通内容树中。其他语言的笔记放在 _translations/<locale>/ 下相同的相对路径中。译文继承公开默认语言笔记的发布状态；设置 publish: false 后，该语言 URL 会显示现有的默认语言回退内容。每个配置的语言都需要在其根目录提供 _locale.yml。name 为必填项；hreflang、dir 和封闭的 messages 目录可选。译文缺失或停用不会让构建失败。对应本地化 URL 会在默认语言正文上短暂显示提示，并从搜索引擎索引与站点地图中排除。

name: 简体中文
hreflang: zh-Hans
dir: ltr
messages:
  search: 搜索

dir 只接受 ltr 或 rtl。文案值必须是字符串，配置键必须属于内置主题文案目录；未知键会让构建失败。省略的文案使用内置英文。语言列表顺序也是语言切换器顺序。

默认语言保留现有 URL。其他语言使用配置的 tag 作为路径前缀，例如 /zh-CN/docs/Getting%20Started/。Minimal 与 Docs 的导航、Search、主题系统页、语言切换、SEO 元数据和语言资源都会保持分区。

语言清单、译文归属、回退页面、SEO 行为和问题排查详见 本地化。

颜色与字体

两个主题共享一小组 CSS 自定义属性。浅色模式使用暖色纸张与表面色，深色模式使用中性黑灰色。蓝色标记链接与焦点，陶土色标记关系与次级注释。

正文和控件使用平台无衬线字体，系统已安装时会优先使用 Noto Sans CJK 或思源黑体。代码使用平台等宽字体。站点不会下载 Web Font，因此具体字形取决于读者操作系统，字号与间距仍保持一致。

请在自己的样式表中覆盖 token，不要编辑带 hash 的构建输出。浅色与深色配色中的文本和焦点对比度都应达到 WCAG AA。

页面属性

编译器为发布行为保留以下笔记属性，并按封闭结构逐项校验：

• publish、title、subtitle、aliases、tags、author、categories 和 description
• permalink、image 和 cssclasses
• created 和 updated
• content_type、date、pinned、nav_order、nav_exclude、tab 和 tabs
• comments、github_markdown 和 related

其他顶层属性可以使用标量或一层标量列表。自定义属性名必须是经过规范化的单行文本，且不能带首尾空白。其中完整的 Wiki 链接只有写成 YAML 双引号字符串时，才会成为普通笔记关系。自定义属性只属于编译器元数据；属性名和原始值不会进入 Liquid、HTML、Feed 或生成的 JSON。

project: "[[portfolio/fauni-search|Fauni Search]]"
references:
  - background
  - "[[docs/development/architecture]]"
related:
  - "[[blog/launch-notes]]"
  - "[[docs/Getting Started|从这里开始]]"

related 是用于精选列表的专用字段。它只接受双引号 Wiki 链接列表，保留书写顺序并去除重复目标，在页面底部以「最新文章」相同的卡片样式显示。生产构建会拒绝断开的相关文章链接。其他自定义属性链接仍会进入直接链接、反向链接和关系图，但不会额外生成一张可见属性表。

aliases、tags、author、categories、cssclasses 和 tabs 是字符串数组，subtitle 是字符串。publish、pinned、nav_exclude 和 comments 使用 YAML 布尔值。tab 是前文说明的封闭映射。github_markdown 只接受 作品集中说明的 URL 或映射形式，并且只能用于作品集项目页。日期使用 ISO 8601。笔记标题依次取自 title、第一个一级标题和文件名。

updated 可选，只有作者明确提供时才会出现在页面元数据中；编译器不会从 Git 推导更新时间。文章发布时间依次使用 date、created 和第一次 Git 提交时间。Atom 条目优先使用显式 updated；未提供时，文章沿用其发布时间。没有 updated 的非文章笔记不会进入订阅源。

Minimal Home 会在文章标题下显示 subtitle，然后使用 description 或编译器生成的正文摘录作为摘要。存在 author 时，摘要页脚会列出作者。author 和 categories 会与 tags 一起进入 Home 的 Topics 区域。条目可以是普通字符串，也可以是指向公开笔记的 Wiki 链接：

---
subtitle: Dreamers among programmers
author:
  - "[[People/Ada Lovelace|Ada]]"
  - Editorial team
categories:
  - "[[AI]]"
  - "[[Machine Learning|ML]]"
---

Wiki 链接条目必须使用 YAML 双引号字符串。可见标签优先使用 | 后的别名，没有别名时使用目标笔记标题。Home Topics 中的每个主题标签都会打开对应的 Blog 筛选；文章摘要中带 Wiki 链接的作者还可以直接打开公开作者页面。在 Minimal Blog 中，标签与分类会一起显示在归档列表的日期下方，并在文章页的发布日期右侧显示为筛选胶囊；tags 与 categories 中的同名项只显示一次。无法解析的 Wiki 链接会产生编译器警告，但仍保留为可筛选文本，不会把 [[...]] 泄漏到站点中。

内容与导航

显式的 content_type: post | doc | page 优先于目录默认值。文章发布时间依次使用 date、created 和第一次 Git 提交时间。生产构建会拒绝没有确定日期的文章。在 Minimal Home 和 Blog 中，设置了 pinned: true 的文章排在普通文章之前，两组内部都保持时间倒序。置顶只影响卡片展示，不改变 Atom Feed 的时间顺序以及上一篇、下一篇文章序列。

Docs 导航沿用内容目录结构。nav_order 对同级文档排序，nav_exclude: true 只移除当前笔记链接，子页面仍然可以访问。所有层级都可以没有 index.md。物理 index.md 不存在时，同级且文件名精确为 README.md 的公开笔记会成为文件夹索引。已有的 index.md 即使未发布也会保留该位置，此时 README.md 仍是普通笔记。公开的根索引始终拥有 /，因此该笔记使用其他 permalink 会被拒绝。没有公开索引的文件夹会打开依次按 nav_order、标题和路径排序的第一个可见子页面。存在文章时，Minimal Home 可以不需要根索引；两者都不存在时，根路径会重定向到第一个可见顶层导航目标。Docs 没有根索引时会重定向到第一项导航。每个 Docs 页面都由服务器渲染完整文档树；JavaScript 导航只替换页面内容与上下文，保留共享外壳。Search 在 Web Worker 中构建索引。局部图谱由编译器投影；浏览器只在打开对话框后读取完整图谱。

修改编译器或适配器边界前，请阅读 架构。