使用 Gatsby 模板发布 Foam 知识库:GitHub Pages 与 Vercel 静态站点实战指南
使用 Gatsby 模板发布 Foam 知识库:GitHub Pages 与 Vercel 静态站点实战指南
本篇指南围绕 Foam 官方文档中基于 Gatsby 的三种社区发布模板展开,完整讲解从本地构建、产物提交到 GitHub Pages 自动部署与 Vercel 手动导入的全流程,并顺带梳理发布前的链接引用定义配置,以及仓库中更新的 foam export 官方发布管线,帮助你为自己的 Foam 工作区选出一条可落地、可上线的静态站点发布路径。
发布前的准备:让笔记对标准 Markdown 工具可见
Foam 的定位是"笔记始终是合法 Markdown、可被多种工具发布"(参见 docs/user/index.md 中的 Publishing 章节与 发布相关文档)。因此在使用任何站点生成器之前,首先要解决的是 wikilink 与标准 Markdown 处理器的兼容问题。
Foam 通过"链接引用定义"(Link Reference Definitions)特性,在笔记末尾自动生成标准 Markdown 引用定义,把 <a href="https://link.gitcode.com/i/4cddeb99a80c26863c562ff60070c3ab" target="_blank">[Data Science]] 这样的 wikilink 转写为 [Data Science]: data-science.md 'Data Science' 形式(详见 [link-reference-definitions.md)。这在 Gatsby/Jekyll 等外部构建工具中是必需的,因为多数站点生成器并不理解 Foam 的 [[双括号]] 语法。
在 VS Code 设置中按发布目标选择模式:
{
"foam.edit.linkReferenceDefinitions": "withoutExtensions"
}
可选值:
"off"—— 关闭(默认值),仅在本机 Foam 内使用时可保持关闭以减少笔记冗余;"withoutExtensions"—— 引用不带文件扩展名,适合 GitHub Pages / Jekyll 这类按路径解析的发布方式;"withExtensions"—— 引用带文件扩展名,适合希望在 GitHub 仓库内直接点击跳转的场景(参见 publish-to-github.md)。
配置完成后,执行命令面板中的 “Foam: Lint Workspace”,Foam 会扫描全部笔记并补齐引用定义。这样发布出来的 Markdown 在任何标准处理器中都能正确解析,不会被构建工具当作非法链接丢弃。
方案一:使用 foam-gatsby-template(推荐起点)
foam-gatsby-template 是发布文档主推的 Gatsby 模板,它把整份 Foam 工作区作为 Gatsby 站点源,支持部署到 GitHub 与 Vercel。该模板与仓库中其他发布方案(Jekyll、Astro/Starlight)并列,是 Foam 生态中成熟的社区发布路径之一。
发布到 GitHub Pages:推送即部署
模板内置了 GitHub Actions 工作流:
- 当代码被推送到
main分支时,自动触发构建并部署到 GitHub Pages; - 无需手动配置 Vercel 或本地构建,属于"零操作"的自动化路径。
使用这一路径时,同样建议先按上文把 foam.edit.linkReferenceDefinitions 设置为 "withoutExtensions" 并执行 "Foam: Lint Workspace",保证生成的引用定义与 GitHub Pages 的 Jekyll 渲染器兼容。仓库内的 GitHub Pages 发布文档还提到,GitHub Pages 基于 Jekyll,因此支持 permalinks、front matter 元数据等能力,模板也允许通过修改 _layouts 与样式来定制外观(详见 publish-to-github-pages.md)。
发布到 Vercel:手动构建与导入
当准备正式发布时,先在本地完成一次完整构建:
cd _layouts
npm run build
构建产物会输出到 _layouts/public 目录。随后:
- 从项目的
.gitignore文件中移除public,否则构建产物不会被提交; - 将
_layouts/public目录提交并推送到 GitHub 仓库; - 登录 Vercel 账号(没有则先注册);
- 在 Vercel 中 Import 该项目,将
_layouts/public选为 Root Directory,点击 Continue; - 为项目命名后点击 Deploy,Vercel 会完成剩余工作。
完成以上五步即部署成功。后续每次推送更新到仓库后,只需在本地重新执行 cd _layouts && npm run build 并提交新的 public 产物,Vercel 就会发布最新版本。
注意区分两条路径:GitHub Pages 走的是"模板内置 GitHub Actions 自动构建",而 Vercel 走的是"本地构建产物 + 手动导入"。前者要求模板仓库本身带 Actions 配置,后者只要求你把
_layouts/public静态产物推送到 Git 仓库。
方案二:使用 foam-template-gatsby-kb
foam-template-gatsby-kb 是另一个 Gatsby 发布模板,目标是构建"知识库"(knowledge base)风格的站点。官方文档给出的托管目标为 Vercel 或 Netlify。
该模板与方案一的主要差异在于站点形态与配置方式:
- 若你希望得到一个更贴近"知识库浏览"体验(分类、归档、阅读视图)的站点,优先考虑本模板;
- 部署时同样需要先本地构建出静态产物,再导入 Vercel / Netlify;构建与产物目录的约定以模板仓库 README 为准。
由于模板各自约定的构建脚本和输出目录可能不同,动手前先查看模板的 README,确认构建命令与需要提交的产物目录。
方案三:使用 foam-template-gatsby-theme-primer-wiki
foam-template-gatsby-theme-primer-wiki 基于 Primer Wiki 主题,官方文档说明它可以托管在 GitHub Pages、Vercel 或 Netlify 三端任意之一。
该模板适合希望获得 Primer(GitHub 原生风格)视觉呈现的用户。三个托管平台的要点分别对应:
- GitHub Pages:利用 GitHub Actions 或直接推送静态产物,配合
withoutExtensions的引用定义模式; - Vercel / Netlify:导入 Git 仓库后由平台自动识别构建框架(模板基于 Gatsby,平台通常会自动检测到 Gatsby preset),按提示指定根目录即可完成部署。
选择模板时可以这样权衡:追求自动化与零成本用方案一(GitHub Pages 自动部署);追求知识库阅读形态用方案二;追求 Primer 视觉风格或需要三端皆可切换用方案三。
三个 Gatsby 模板的对比小结
| 模板 | 目标形态 | 支持托管平台 | 部署方式 |
|---|---|---|---|
| foam-gatsby-template | 通用静态站点 | GitHub Pages、Vercel | GitHub Actions 自动部署;或本地构建后导入 Vercel |
| foam-template-gatsby-kb | 知识库浏览 | Vercel、Netlify | 构建产物导入平台 |
| foam-template-gatsby-theme-primer-wiki | Primer Wiki 风格 | GitHub Pages、Vercel、Netlify | 构建产物导入平台或 Actions 部署 |
发布相关的配套能力
Front Matter 属性
无论使用哪个 Gatsby 模板,笔记顶部的 YAML front matter 都会被站点生成器读取。Foam 定义了几个具有特殊含义的属性(详见 note-properties.md):
| 属性 | 作用 |
|---|---|
title |
覆盖图/页面中显示的名称,不受文件名或首行标题限制 |
type |
用于在图视图中区分笔记类型,默认 note |
tags |
为笔记添加标签,便于发布站点做聚合 |
alias |
为笔记添加别名,别名会出现在链接自动补全中 |
数学公式(KaTeX)
若你的知识库包含 LaTeX 公式,可参考仓库中的 math-support-with-katex.md。其中说明:由于 jekyll-katex 插件与 GitHub Pages 不兼容,KaTeX 方案需要切换到 Vercel 部署;对 Gatsby 模板而言,只需保证构建产物中正确加载 KaTeX 的 JS/CSS 资源即可,原理一致。
延伸:仓库中的官方发布管线新方向
除了上述 Gatsby 社区模板,当前仓库还包含一条由官方推进的静态站点发布管线,可作为未来迁移的参考。
在 packages/foam-cli/src/commands/export.ts 中,Foam CLI 提供了 foam export 命令,默认将工作区导出为 Astro/Starlight 站点:
foam export [workspace-dir] --out <dir> [options]
常用选项:
--target <name>—— 导出目标,当前默认且唯一支持starlight;--out <dir>—— 生成站点(Astro/Starlight 工程)的输出目录,必填;--title <text>/--description <text>—— 站点标题与描述;--content-root <path>—— 相对于工作区根目录要导出的笔记子树;--homepage <route>—— 首页路由或源路径;--site-url <url>—— 公开站点 URL,用于 canonical、sitemap 等元数据。
命令底层通过 buildSite()(来自 @foam/core)把工作区解析、过滤、转换为一组 Markdown 与 JSON 产物,再交由 StarlightTarget 物化出可运行的 Astro/Starlight 工程(该目标实现了 PublishTarget 接口,负责 locator、asset-strategy、link-rewriter 等职责)。
仓库中的设计文档进一步阐述了这一方向的技术选型:两层发布架构(improved-static-site-generation.md)提出"Foam 拥有解析、图解析、发布过滤与内容转换,站点框架只负责渲染与导航外壳";static-site-publishing-research.md 则对比了 Astro、Starlight、Markdoc、Quartz、Docusaurus 等方案,最终推荐 Astro + Starlight 作为默认站点栈。整体数据流为:
Foam workspace -> foam-publish -> Markdown + JSON -> Astro/Starlight -> static HTML
这条管线与本文的 Gatsby 模板发布路径目标一致(生成可部署的静态站点),差异在于:Gatsby 模板面向社区维护、开箱即用;而 foam export 走官方 TypeScript 管线,后续计划支持 backlinks、block anchors、embeds、graph 数据、publish 可见性规则以及 foam-query 的构建期渲染(详见 improved-static-site-generation.md 的增量交付计划)。
常见问题与排查建议
public没有被推送到 GitHub:检查.gitignore,确保已把public从忽略列表中移除;Vercel 导入的是仓库中的静态产物目录,而非运行构建。- 部署后 wikilink 404:确认已执行 "Foam: Lint Workspace" 且
foam.edit.linkReferenceDefinitions与托管平台匹配(GitHub Pages 用withoutExtensions)。 - 构建命令找不到
_layouts目录:仅foam-gatsby-template使用_layouts作为 Gatsby 工程目录;另两个模板的构建目录以各自 README 为准。 - 不确定选哪个平台:追求零成本自动化选 GitHub Pages;需要自定义域名、CI 构建托管选 Vercel;Netlify 适合偏好其工作流的团队。