jekyll-obsidian

English | 简体中文

jekyll-obsidian 可以将任意 Markdown 文件夹发布为通用 Jekyll 站点或文档手册，Obsidian 知识库也可以直接使用。内容仍可通过 Obsidian 或任意文本编辑器直接编辑。只需将项目自带的 website/ 目录复制到仓库并推送，GitHub Actions 就会完成构建并发布到 Pages，本地无需安装工具链或运行构建命令。

把 Markdown 文件夹直接变成完整的博客或文档站。推送到 GitHub 后，GitHub Actions 会自动构建并发布，本地不用安装构建工具，也不用运行构建命令。

在线预览：sinputer.top/jekyll-obsidian

每次构建可选择一个内置主题：

• minimal 将自定义 Home 页面、最近文章、完整 Blog、文档和显式配置的自定义栏目组合为个人或组织站点。
• docs 提供文档目录树以及上一篇、下一篇导航。

两个主题均默认启用搜索、Wiki 链接阅读预览、页面大纲、笔记关系和交互式局部图谱。当笔记与另一篇公开笔记存在链接或嵌入关系时，局部图谱位于右侧上下文栏顶部；孤立笔记和仅自链笔记不显示它。图谱上的两个控件可分别打开完整公开图谱，或放大当前笔记的邻接关系。完整图谱仍包含所有公开笔记；站点不会生成独立的 /graph/ 页面。

切换主题不会改变笔记 URL。默认构建和部署主题为 minimal。两个主题都支持通过 _translations/<locale>/ 发布语言覆盖层，也可以为文章接入 GitHub Discussions 评论。存在对应配置但省略 enabled 时，本地化仅在 docs 中默认启用，评论仅在 minimal 中默认启用。

语言清单、默认语言与译文的职责边界、回退页面和 SEO 行为详见本地化指南。

Minimal 还提供 Blog、标签、Atom 订阅源、联系方式、源码操作，以及自动检测并生成项目卡片的作品集。项目页可以直接使用一篇公开 GitHub Markdown 作为正文。两个主题都会生成 Search 与 Graph 数据、canonical 元数据、站点地图、404 页面和不含 frontmatter 的 Markdown 资源。可选流量统计支持 Cloudflare Web Analytics 或 Google Analytics，配置前始终关闭。

发布前须知

使用 GitHub Pages 部署时，本地计算机无需安装 Ruby、Node.js、Bundler、npm 或浏览器。生成的 GitHub Actions 工作流会安装完整构建工具链。

GitHub Free 的公开仓库可以使用 GitHub Pages，因此公开的 jekyll-obsidian 站点无需付费托管。

发布策略决定哪些内容进入生成的站点，但不会让仓库中其他已提交文件变成私密内容。任何能读取仓库的人同样可以读取未发布笔记，因此不要提交密钥、个人记录或其他私密资料。

公开笔记链接到 Canvas 或 Bases 文件时，这些文件会作为下载内容发布。提交前请检查其中是否包含未发布材料的摘录或引用。

集成到你的仓库

1. 将完整的 website/ 目录复制到仓库根目录。
2. 在 website/ 之外选择一个内容目录，例如 docs/，并添加至少一篇公开 Markdown 笔记。
3. 在仓库根目录运行集成命令。

在 macOS、Linux 或 WSL 中运行：

website/bin/integrate --source docs

在原生 Windows 的 PowerShell 中运行：

.\website\bin\integrate.cmd --source docs

该命令默认使用 --source docs --theme minimal。它无需安装依赖或访问 GitHub，即可生成 .github/jekyll-obsidian.yml 和 .github/workflows/pages.yml。

你的仓库将具有以下结构：

repository/
├── docs/
│   └── Start.md
├── website/
└── .github/
    ├── jekyll-obsidian.yml
    └── workflows/
        └── pages.yml

打开 GitHub 中的 Settings → Pages → Build and deployment，将 Source 设为 GitHub Actions。提交并推送内容目录、website/ 和生成的 .github/ 文件。你不需要创建 gh-pages 分支、配置部署密钥，也不需要手动设置 url 和 baseurl。

除非传入 --force-workflow，否则集成命令不会覆盖不属于本项目的 Pages 工作流。已有配置、Windows 使用方式和冲突处理详见宿主集成。

预览已部署站点

等待默认分支上的 Verify and deploy Pages 工作流执行成功。GitHub 会在工作流的 deploy 作业和 Settings → Pages 中显示部署地址。

未配置自定义域名时，地址通常为：

• 普通项目仓库：https://<owner>.github.io/<repository>/
• 仓库名称为 <owner>.github.io：https://<owner>.github.io/

如果配置了自定义域名，请使用 Settings → Pages 中显示的地址。工作流会读取 GitHub Pages 元数据，并自动为该地址构建站内链接。工作流和自定义域名设置详见部署指南。

配置与发布

生成的 .github/jekyll-obsidian.yml 是宿主仓库的配置文件。你可以在其中设置站点标题、描述、语言、仓库链接、内容类型和功能开关。请保留 website.source 与 website.theme 周围的托管标记，并通过带有相应参数的 website/bin/integrate 命令修改这两个值。

所有配置均位于根级 website: 映射中。

两个主题都可以通过 Giscus 将文章评论存储在 GitHub Discussions 中。评论默认使用发布仓库，也可以指向另一个公开仓库。存在 website.comments 但省略 enabled 时，minimal 默认启用评论；docs 需要显式设置 website.comments.enabled: true。在 Discussions 或 Giscus App 尚未就绪时启用评论不会导致构建失败；Giscus 配置不完整时会产生警告，并显示非交互式回退内容。仓库设置、讨论串标识、隐私边界和故障排查详见评论指南。

使用 Obsidian 或任意 Markdown 编辑器打开内容目录。默认情况下，只有 frontmatter 中包含 YAML 布尔值 publish: true 的笔记才会进入站点：

---
publish: true
title: A public note
tags:
  - example
---

字符串 "true" 和 "yes" 不会被接受。如需递归发布整个文件夹，请把相对于内容根目录的路径加入 website.content.publish_by_default；使用 . 可选择完整内容树。默认发布范围内的单篇笔记仍可通过 YAML 布尔值 publish: false 排除。生成内容快照前会排除 Obsidian 的 .obsidian/ 状态目录和 .trash/ 目录。

内容根目录及其所有子目录都可以不包含 index.md。Minimal 会先在 Home 页面显示公开的根 index.md，再显示最近六篇文章；没有根页面时，Home 仍可显示文章流。缺少索引的文件夹会链接到排序后的第一个公开页面。内容目录中没有任何公开笔记时，构建仍会失败。

在宿主仓库根目录更新已发布 tag 对应的安装：

website/bin/update --check
website/bin/update

更新器会在隔离的临时仓库中获取官方日历版本 tag，验证当前快照，并仅刷新工具托管的文件；审阅和提交仍由你决定。它不会为宿主添加 remote，也不会运行 git pull、git add、git commit 或 git push。更新需要官方 annotated release。旧安装首次更新时，其已提交的 website/ 必须与某个官方 tag 完全一致；否则需要先手工完整替换到一个带 tag 的快照。来源锁定、退出码、Windows 命令和恢复行为详见宿主集成。

可选的本地预览

本地预览需要在 macOS、Linux 或 WSL 中安装 Ruby 4.0.x、Node.js 26.x 和 Git。原生 Windows 用户可以在 WSL 中运行以下命令：

website/bin/setup
website/bin/dev

本地服务器默认地址为 http://127.0.0.1:58000/。website/bin/dev 默认使用 Minimal 主题；传入 --theme docs 可预览独立文档手册。

在仓库根目录运行 website/bin/clean 可删除生成站点、Jekyll 与前端缓存、测试报告、覆盖率结果和构建临时目录；已安装的 Ruby 与 Node.js 依赖会保留。

使用指南

• 宿主集成：介绍如何安装到其他仓库及后续更新。
• 快速开始：介绍 GitHub Actions 发布、写作和可选本地预览。
• 语法：介绍支持的 Obsidian 风格 Markdown。
• 自定义：介绍站点信息、主题、导航和功能。
• 作品集：介绍项目集合和公开 GitHub Markdown 正文。
• 流量统计：介绍可选的 Cloudflare 与 Google 访问统计。
• 评论：介绍 GitHub Discussions 配置和隐私边界。
• 本地化：介绍译文、回退页面和本地化 SEO。
• 部署：介绍 GitHub Pages、URL 路径和自定义域名。

贡献者可以继续阅读开发者指南。

许可证

MIT