Actual Budget 社区文档站完全指南基于 Docusaurus 3 的构建、开发与部署【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual Budget 是一个本地优先local-first的个人财务管理应用其官方社区文档网站由 packages/docs 目录承载基于 Docusaurus 3 静态站点生成器构建。本文以该文档站自身为讲解对象完整梳理它的技术栈、本地开发、静态构建、部署流程与内容规范并结合仓库中的配置文件与源码插件带你理解这个文档站的完整运作机制——读完你将能够独立搭建、运行、构建并贡献该文档站。一、文档站概览Actual Budget 的活文档Actual Budget 的文档目录以 README 开篇即 packages/docs/README.md它定位为Actual Budget 社区文档网站Community Documentation使用Docusaurus 3构建——这是一个基于 Node.js 的现代静态网站生成器。由于项目本身依赖 Node.js 运行环境本地开发者在机器上运行 Actual 时通常已具备 Node 环境因此可以顺畅地运行这套文档站。从 packages/docs/package.json 可以看到其核心技术栈docusaurus/core/docusaurus/preset-classic版本为^3.10.2这是 Docusaurus 3 系列使用docusaurus/plugin-content-docs承载文档、docusaurus/plugin-client-redirects管理 URL 重定向、docusaurus/plugin-ideal-image做图片响应式优化docusaurus/theme-mermaid使文档支持 Mermaid 图表渲染easyops-cn/docusaurus-search-local提供站内本地搜索r74tech/docusaurus-plugin-panzoom提供图表缩放pan/zoom能力前端使用 React 19.2.7 与 prism-react-renderer 做代码高亮。README 还特别强调这份文档是社区文档欢迎任何人参与完善但官方文档只对特定的安装方式进行维护详见下文其余变体由作者自行负责维护。二、官方支持的安装方式README 明确列出当前 Actual Budget 官方文档仅支持以下安装方式本地安装自有机器Actual-server自托管服务器Desktop apps桌面应用Fly.io云平台部署PikaPods托管服务Docker容器部署这一划分与文档站的侧边栏结构完全对应。查看 packages/docs/docs-sidebar.js 中的 Installing Actual 分类本机安装下分列install/docker、install/cli-tool、install/desktop-app、install/build-from-source云部署下分列install/pikapods、install/fly。如果你的安装方式是其他变体README 建议在自己的博客/Medium/Tumblr 上撰写并提交 PR将链接挂到安装概览页的附加安装选项列表中——但随之而来的是你将对这些非官方安装说明负责。一旦它们过时、用户大量求助而社区无法解决维护者可能会移除该链接。三、贡献流程Issue 与 Pull RequestREADME 的贡献章节确立了文档站的内容协作方式发现未文档化的功能如果你知道 Actual 的某部分没有文档可以新建一个 Issue使用 documentation 模板文档团队会跟进处理也可以自己动手撰写。提交 Pull Request提交前请确保内容完整。README 强调维护者会定期检查 PR只要 PR 处于打开状态就有较大概率被合并。所有提交的文档在合并前都会经过校对与修订proofread and amended这是文档质量的保障流程被修订并不代表否定而是为了确保进入 master 的每篇文档都达到发布标准。结合源码看onBrokenLinks: throw与onBrokenAnchors: throw配置见 packages/docs/docusaurus.config.js意味着任何失效链接都会直接导致构建失败这从工具链层面强制保证了文档链接的完整性。四、本地开发安装依赖与启动开发服务器README 给出了标准的本地开发三步流程。首先把仓库克隆到本地例如git clone https://gitcode.com/GitHub_Trending/ac/actual进入packages/docs目录后1. 安装依赖$ yarn由于本仓库采用 Yarn workspace 管理见仓库根目录 package.json 与yarn.config.cjspackages/docs的开发依赖actual-app/ci-actions使用了workspace:*协议引用同仓库内的 packages/ci-actions因此在仓库根目录执行yarn一次即可装齐所有工作区依赖。2. 启动本地开发服务器$ yarn start这条命令会启动一个本地开发服务器并自动打开浏览器窗口。注意 packages/docs/package.json 中的实际脚本为start: node scripts/generate-upcoming-release-notes.mjs docusaurus start也就是说在启动开发服务器之前会先执行 scripts/generate-upcoming-release-notes.mjs自动从仓库根目录的upcoming-release-notes/目录生成docs/upcoming-release-notes.md页面然后才启动 Docusaurus。绝大多数改动Markdown 正文、代码块等都会热更新实时反映无需重启服务器但修改配置文件如docusaurus.config.js后仍建议重启。五、静态构建与产物$ yarn build该命令同样会先执行generate-upcoming-release-notes.mjs再调用docusaurus build最终把整个站点生成到build目录下的静态文件。产物可以部署到任意静态内容托管服务。构建过程的质量门禁值得一提docusaurus.config.js中设置了onBrokenLinks: throw、onBrokenAnchors: throw并且markdown.hooks.onBrokenMarkdownLinks同样为throw——任何损坏的链接、锚点都会让构建直接失败而不是静默警告。这意味着构建通过本身就是文档链接有效性的强验证。此外packages/docs/src/remark/enforce-doc-links.js 是一个自定义 Remark 插件它在构建期对 docs/ 页面实施链接卫生检查主要规则包括文档页必须使用.md而非.mdx扩展名该包明令禁止 .mdx禁止站内绝对链接/docs/...、/blog/...必须改用相对.md路径指向其他.md文件的相对链接必须带扩展名且不能指向.mdx文件通过解析 frontmatter 中的slug:建立 slug 缓存捕获用 Docusaurus slug 代替真实文件名的错误链接并给出正确路径建议链接指向目录时存在index.md会提示改为dir/index.md形式。这些规则在构建期以抛错形式强制执行从源头杜绝了文档链接腐烂link rot。六、部署到 GitHub PagesREADME 提供了两种yarn deploy方式使用 SSH 认证$ USE_SSHtrue yarn deploy使用 Git 用户名认证HTTPS$ GIT_USERYour GitHub username yarn deploy如果你使用 GitHub Pages 托管这是最便捷的方式它会在构建网站后自动推送到gh-pages分支。不过需要注意docusaurus.config.js 中配置了projectName: actualbudget.github.io、organizationName: actualbudget、deploymentBranch: main——即该文档站实际部署分支为main而非默认的gh-pages部署前请确认你的仓库分支命名与配置一致。仓库还提供了面向 Netlify 的独立配置 packages/docs/docusaurus.netlify-config.js它基于主配置展开...baseConfig仅覆盖baseUrl: /供 Netlify 构建时使用。七、站点配置深度解析packages/docs/docusaurus.config.js 是整个文档站的中枢配置README 未展开的细节在这里一目了然站点元信息title: Actual Budget、tagline: Your finances - made simple路由根路径为docs侧边栏由 docs-sidebar.js 定义导航栏Features、Tour、Docs、Blog、Community、Download、Donate、Discord、GitHub 等条目代码高亮prism-react-renderer的 GitHub 亮色主题与 Dracula 暗色主题并额外注册了nginx语言用于反向代理配置示例图表支持markdown.mermaid: truedocusaurus/theme-mermaid文档中的 Mermaid 图表可被渲染为交互式图形并配合 panzoom 插件支持缩放拖拽URL 重定向docusaurus/plugin-client-redirects内置了两条重定向/contact→/docs/community/以及/docs/actual-server-repo-repo-move→/docs/install/针对 actual-server 仓库迁移后的旧链接本地搜索easyops-cn/docusaurus-search-local启用hashed: true索引全部文档页indexDocs: true语言设为英文图片优化docusaurus/plugin-ideal-image将图片压缩至 70% 质量、宽度上限 1030px并生成 640px 至 1030px 之间的多档响应式版本。八、文档内容组织侧边栏的编排逻辑packages/docs/docs-sidebar.js 将整个文档站组织为四大侧边栏tourSidebar产品导览用户界面、预算、账户、报表、计划schedules、收款方payees、规则rulesdocs主文档按分类展开Getting Started新手路线图、安装 Actual、从零开始、信封预算法、从 YNAB 迁移等Using Actual预算、计划、账户与交易、银行同步、报表、设置、自定义主题、实验性功能Sync Data Safety同步、文件管理、备份与恢复Self-Hosting Your ServerHTTPS、反向代理、OAuth 认证、多用户、HTTP 头认证For DevelopersAPI 参考、CLI、ActualQL 查询语言Help SupportFAQ、故障排查communitySidebar社区愿景、社区仓库、开源 Issue/Feature Requests、Contributing项目结构、数据库、架构、功能开关、Electron、迁移、测试、代码风格、i18n、发布、Windows、文档写作规范、项目领导力、Release Notes、Upcoming Release Notes、Discord。其中contributing/writing-docs正是 README 中提到的写作指南落地页涵盖文档结构约定与格式一致性建议新贡献者应首先阅读。九、即将发布页面自动化的发布说明流水线README 末尾特别讨论了发布说明的写作规范而仓库的自动化脚本把这一规范落到了实处。scripts/generate-upcoming-release-notes.mjs 是文档站与 CI 流程的衔接点它从仓库根目录的upcoming-release-notes/目录读取每个 PR 的发布说明文件每文件对应一个已合并但未发布的变更调用actual-app/ci-actions中的parseReleaseNotes/formatNotes工具解析并按分类格式化生成packages/docs/docs/upcoming-release-notes.md页面顶部用:::info提示框注明这些变更已合并但尚未进入稳定版会出现在 nightly 构建中该页面在每次yarn start/yarn build时自动重新生成见 package.json保证始终反映最新未发布变更且页头注释明确要求不要手工编辑。这与 README 描述的文档站属性一致文档站不像主项目那样按版本管理而是一份活文档living document。合并到 master 的提交以PR 标题 PR 编号作为 commit messagePR 描述作为扩展的 Git 提交描述——这正是发布说明的基本素材。想要写出高质量发布说明的贡献者建议先参考文档站 Contributing 部分的Writing Good Release Notes指引再配合这套自动化生成机制提交 PR。十、给贡献者的实践清单综合 README 与源码贡献 Actual Budget 文档站的完整流程可以归纳为克隆仓库并进入packages/docs执行yarn安装依赖启动yarn start在本地浏览器中实时预览新增/修改docs/下的 Markdown 文件遵循链接卫生规则相对路径、带.md扩展名、不指向.mdx文档页中的username会由 src/remark/mentions.js 自动转换为 GitHub 用户链接运行yarn build做最终验证——任何失效链接都会使构建报错提交完整、经过校对的内容通过 Pull Request 合入 masterPR 标题与描述将成为发布说明的来源。这套Docusaurus 3 自定义 Remark 校验 发布说明自动生成的文档工程化方案既保证了文档站的高质量与链接健壮性也让社区协作保持顺畅——这正是 Actual Budget 文档站可持续运营的底层机制。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考