通过 GitHub Actions 发布 Markdown 文件夹，需要时再使用本地预览。
快速开始
Jekyll Obsidian 可以发布任意 Markdown 文件夹，包括 Obsidian 知识库。继续在 Obsidian 或其他文本编辑器中写作，然后推送即可。GitHub Actions 会安装构建工具、检查内容并把站点部署到 Pages。本地无需安装 Ruby 或 Node.js，也不用运行构建命令。
项目自带的内容位于 website/docs/，发布实现位于 website/。Obsidian 可以直接打开内容目录，无需转换或额外导出。
通过 GitHub Actions 发布
将 Jekyll Obsidian 加入其他仓库时，请复制完整的 website/ 目录，并按照 宿主集成操作。其中的无依赖命令可以直接生成宿主配置和 Pages 工作流，无需安装 Ruby 或 Node.js：
提交内容目录、website/ 和生成的 .github/ 文件。在 GitHub 中将 Settings → Pages → Build and deployment → Source 设置为 GitHub Actions，然后推送。部署完成后，Verify and deploy Pages 工作流会显示最终地址。
发布一篇笔记
在配置的内容目录中创建 Markdown 文件，并添加包含 YAML 布尔值的 frontmatter：
---
publish: true
title: 我的第一篇笔记
tags:
- fieldwork
---
这里必须使用布尔值 true，不能使用字符串 "true" 或 "yes"。未设置默认发布范围时，省略 publish 的 Markdown 文件不会进入 HTML、Search、Graph 数据、订阅源、站点地图或复制的附件。
如需递归发布一个目录，请把它相对于内容根目录的路径加入 website.content.publish_by_default。特殊路径 . 表示完整内容树。在这个范围中，可以用 publish: false 排除单篇笔记；范围之外的笔记仍可以通过显式的 publish: true 发布。执行发布检查前，编译器会排除内容目录中的 .obsidian/ 和 .trash/。
发布策略只控制生成结果，不能限制仓库访问。不要把密钥、个人记录或其他私密内容放进他人可以读取的仓库。
添加链接与附件
继续使用 Obsidian 中的写法：
只有公开笔记、其 image 属性或嵌入闭包能够访问的附件才会被复制。image 属性还会提供页面的公开 og:image 地址。只出现在私密笔记中的文件会被忽略。完整写作契约请参阅 语法。
让工作流检查推送
每个拉取请求和默认分支推送都会运行生产编译器与项目检查。生产构建遇到歧义或私密嵌入、循环、路径逃逸、符号链接和 URL 冲突时会停止。普通的未解析链接仍会显示，同时产生警告。
合并或分享站点前，请检查工作流结果。部署作业和 Settings → Pages 都会显示公开地址。项目路径、自定义域名和受信任部署作业详见 部署。
可选的本地预览
只有需要本地预览或准备修改实现时，才需要安装 Ruby 4.0.x、Node.js 26.x 和 Git。请使用 macOS、Linux 或 WSL。原生 Windows 可以通过 website\bin\integrate.cmd 完成集成和部署，再使用 WSL 运行 Jekyll 开发命令。
在仓库根目录运行：
website/bin/setup 会在 website/ 中安装锁定版本的 Ruby 与 Node 依赖。website/bin/dev 会监视配置的内容和站点源码，在需要时重新构建前端资源，并默认用 Minimal 提供 website/_site 的本地预览。传入 --theme docs 可以预览文档手册。运行 website/bin/dev --help 可查看专用的 --host、--port、--baseurl 和 --theme 参数及其默认值。
文件监听始终启用。每次变更都会执行完整的原子重建，避免全局导航、搜索、关系图数据或已删除页面变得陈旧。因此，website/bin/dev 不接受 Jekyll 的 --watch、--incremental，也不接受 -- 后的任意透传参数。
如需在本地复现生产构建，请运行：
JEKYLL_ENV=production
目标目录始终解析到站点目录下，因此 _site 实际写入 website/_site。修改实现的贡献者还应阅读 开发者指南。