Joplin 文档站点构建指南:基于 Docusaurus 2 的 readme 到网站发布全流程

原创2026-09-11 21:19:101,883 阅读
文章标签:知识管理桌面应用移动开发跨平台后端插件系统笔记

Joplin 文档站点构建指南:基于 Docusaurus 2 的 readme 到网站发布全流程

Joplin 官方文档站(Help / News 等页面)并非手工编写 HTML,而是由 packages/doc-builder 包基于 Docusaurus 2 搭建,将仓库内 readme/ 目录的 Markdown 文档自动转换为可发布的静态站点。本文以 packages/doc-builder/README.md 为骨架,结合仓库内构建脚本与配置源码,完整讲解从「Markdown 生成 MDX」「本地开发构建」「Crowdin 多语言翻译」到「生产发布」的每一步,读完即可在本地跑起 Joplin 文档站点并理解其底层转换原理。

一、doc-builder 包概览:技术栈与定位

packages/doc-builder 是 Joplin monorepo 中专用于构建文档网站的工作区包。从 packages/doc-builder/package.json 可以看到其核心依赖:

  • @docusaurus/core / @docusaurus/preset-classic 均为 2.4.3,属于 Docusaurus 2 静态站点生成器;
  • @docusaurus/theme-mermaid 提供 Mermaid 图表的 MDX 渲染支持;
  • docusaurus-lunr-search 提供站内全文搜索(Lunr 索引);
  • @docusaurus/plugin-client-redirects 用于旧 URL 重定向;
  • react / react-dom 17、prism-react-renderer 负责代码高亮主题;
  • 引擎要求 node >= 16.14,这是本地运行的最低前提。

在构建链路中,doc-builder 只负责「文档」部分(Help 与 News 页面),网站首页、Plans、Brand 等页面则由 packages/tools/website/build.ts 通过 Mustache 模板渲染(详见 packages/tools/website/README.md)。两条流水线最终汇合,输出到 joplin-website/docs 目录。

二、开发流程第一步:从 readme 生成 MDX 文件

Joplin 的文档源文件统一存放在仓库根目录的 readme/ 下(如 readme/index.md、readme/apps、readme/news)。Docusaurus 并不能直接消费这些源文件,因此需要先用 processDocs 脚本把它们转换成带 front matter 的 MDX。

在 packages/tools 目录下执行:

node website/processDocs.js --env dev

该命令的核心实现在 packages/tools/website/processDocs.ts,它内部维护了 dev 与 prod 两套环境配置:

const configs: Record<string, Config> = {
	dev: {
		baseUrl: 'http://localhost:8077',
		docusaurusBuildCommand: 'buildDev',
		docusaurusBuildEnabled: true,
	},
	prod: {
		baseUrl: 'https://joplinapp.org',
		docusaurusBuildCommand: '_build',
		docusaurusBuildEnabled: true,
	},
};

可见 --env 决定了两件事:写入 front matter 的站点基准 URL(WEBSITE_BASE_URL),以及随后自动执行的 Docusaurus 构建命令(buildDev 或 _build)。若只想转换文档而不构建,可追加 --docuBuild false 关闭 docusaurusBuildEnabled(见 processDocs.ts)。

2.1 转换管线里发生了什么

processMarkdownDoc(processDocs.ts)是转换的核心,其工作流为:

  1. 剥离 front matter:通过 stripOffFrontMatter(packages/tools/website/utils/frontMatter.ts)解析文档开头的 --- 块,支持 created、updated、source_url、forum_url、tweet 以及 Docusaurus 侧的 sidebar_label、sidebar_position、date、title、description、image 等字段;
  2. markdown-it 分词转换:用 MarkdownIt({ breaks: true, linkify: true, html: true }) 解析 Markdown,并在 core 规则链上挂载自定义 converter,把 token 逐一遍历,将段落、表格、列表、图片、链接等转写为 MDX 兼容语法。值得注意的细节包括:style 属性会被 style-to-js 转成 JSX 对象、图片路径会补上 / 前缀、表格会被 markdownUtils.createMarkdownTable 重建为对齐规整的 MDX 表格;
  3. 链接重写:processUrls 把形如 https://github.com/laurent22/joplin/blob/dev/readme/xxx.md 的 GitHub 链接改写为站内 /help/xxx 路由(processDocs.ts),保证站点内文档互链不跳出站外;
  4. 注入捐赠链接与讨论链接:每个文档标题后自动插入 donateLinks HTML 块;若源文档 front matter 带 forum_url,文末会追加 "Discuss on the forum" 跳转(processDocs.ts);
  5. OpenGraph 元信息:调用 extractOpenGraphTags(packages/tools/website/utils/openGraph.ts)从正文自动抽取标题(截断到 70 字符)、描述(截断到 200 字符)与首张图片,写回 front matter 的 title、description、image,供社交分享与 SEO 使用;
  6. 增量写入:目标文件已存在时先比对 MD5,内容一致则跳过写入,避免无谓的磁盘 IO 与 nodemon 重编译循环。

2.2 输出到哪里

main() 函数(processDocs.ts)把 readme/ 下的 .md 文件递归处理到 packages/doc-builder/help,把 readme/news/ 处理到 packages/doc-builder/news,并把 _category_.yml 原样复制以保留侧边栏目录结构。同时会执行 deleteUnprocessedFiles 清理目标目录中已不再存在的旧文件,保证生成结果与源文档严格同步。readme/ 下还有一份排除清单(_i18n、cla.md、download.md、privacy.md 等),这些文件不进 Help 文档,而由 build.ts 单独渲染为站内独立页面。

三、构建文档站点:buildDev 与按语言构建

processDocs.js 默认会顺带完成 Docusaurus 构建,但作者在 README 中明确提示它「耗时很长」。日常开发建议直接从 packages/doc-builder 单独执行构建命令:

# 开发构建(不压缩、开发模式)
WEBSITE_BASE_URL=http://localhost:8077 yarn buildDev

buildDev 在 package.json 中的定义为 NODE_ENV=development docusaurus build --no-minify。WEBSITE_BASE_URL 会被 docusaurus.config.js 读取并写入站点的 url 与 favicon,同时注入导航栏 Logo 的 href。该环境变量在开发模式下必须设置,否则导航与静态资源链接会指向空路径。

3.1 只构建某个语言版本

当需要验证特定语言的页面效果时,追加 --locale 参数:

WEBSITE_BASE_URL=http://localhost:8077 yarn buildDev --locale fr

这属于 Docusaurus 原生多语言构建能力,仅针对 fr 生成页面。注意可用的语言由 docusaurus.config.js 的 i18n.locales 决定:

i18n: {
	defaultLocale: 'en',
	locales: ['en', 'fr', 'de'],
},

当前仓库中 doc-builder 侧声明了 en / fr / de 三种语言;而网站整体(含首页、Plans 等 Mustache 页面)支持的语言更多,由 packages/tools/website/utils/supportedLocales.ts 集中管理,包括 en_GB(pathPrefix: '')、fr_FR(fr)、de_DE(de)、zh_CN(cn),并携带 lang、hreflang 等 SEO 元数据。新增一种语言时,需要同时考虑这两处配置。

3.2 断链即失败的策略

docusaurus.config.js 设置了 onBrokenLinks: 'throw'、onBrokenMarkdownLinks: 'warn':任何内部链接失效都会直接中断构建,这保证了文档站上线前链接质量;代价是新增文档时必须同步更新 sidebars.js 之外被引用到的链接。侧边栏本身采用全自动生成(packages/doc-builder/sidebars.js):helpSidebar: [{ type: 'autogenerated', dirName: '.' }],只需保持 help/ 目录结构与 _category_.yml 正确即可。

四、开发热更新与「生产模式」预检

日常编辑文档时,在 packages/doc-builder 下运行:

yarn start

它会启动 Docusaurus 开发服务器(见 package.json 中 start 脚本,内含 WEBSITE_BASE_URL=http://localhost:8077 与 --no-minify),支持 Markdown/MDX 的热重载,适合高频迭代。

但 README 特别提醒:开发服务器不会执行生产环境才生效的插件(如客户端重定向、Lunr 搜索索引、sitemap 生成等)。因此当需要验证「生产条件」下的真实效果时,先在 doc-builder 中按第二节的方式完成构建,然后在仓库根目录运行:

yarn watchWebsite

该脚本(定义在根 package.json 的 watchWebsite)用 nodemon 监听 Assets/WebsiteAssets、packages/tools/website、packages/doc-builder/build 等目录,一旦有变更就执行 node packages/tools/website/build.js,并通过 http-server --port 8077 ../joplin-website/docs 提供预览。也就是说:它把 doc-builder 的构建产物(build/ 目录)与静态资源合并拷贝到 joplin-website/docs,再用静态服务器按生产形态托管。

4.1 一键全量构建:buildWebsite

根目录的 buildWebsite 脚本串联了整条链路:

node ./packages/tools/website/processDocs.js --env prod
  && node ./packages/tools/website/build.js
  && yarn buildPluginDoc
  && yarn buildSettingJsonSchema

即:① 生成 MDX 并以生产模式构建 Docusaurus 文档;② 用 build.ts 渲染首页、Plans、Brand、download/privacy/donate 等 Mustache 页面并按语言目录归档;③ 生成插件文档;④ 生成设置项 JSON Schema。build.ts 开篇会强校验输出目录 joplin-website/docs 必须已存在,否则直接抛错(build.ts),因此首次构建前需先创建该目录(或克隆对应的 joplin-website 仓库)。

五、旧链接重定向与站内搜索

5.1 client-redirects 重定向规则

历史文档曾经位于 /help/apps/xxx、/help/about/xxx、/help/dev/spec/xxx 等路径下,为了不破坏存量书签与搜索引擎收录,docusaurus.config.js 中通过 @docusaurus/plugin-client-redirects 配置了多组重定向:

  • /help/apps/{attachments|clipper|config_screen|conflict|desktop|markdown|mobile|...} → /{同名页面};
  • /help/about/{prereleases|principles|release_cycle|stats} → /{同名页面};
  • /help/dev/spec/... 与 /help/api/... → 去掉 help 前缀后的新路径;
  • /help/about/changelog/desktop → /changelog,其余平台 → /changelog_{平台名};
  • /help/faq → /faq,/help/apps/sync/e2ee → /e2ee,/help/api → /api/overview。

其中 plugins 被特意注释掉重定向,因为该 URL 现已被插件发现站占用,注释说明了原因(docusaurus.config.js)。这套规则由 createRedirects(existingPath) 函数在构建时对每个已生成路径求值,异常时打印 existingPath 便于定位。

5.2 Lunr 全文搜索与 Mermaid

docusaurus-lunr-search 插件在构建期为所有文档建立离线搜索索引,无需外部搜索服务即可实现站内全文检索。同时 markdown: { mermaid: true } 与 @docusaurus/theme-mermaid 让 Markdown 中的 ```mermaid 代码块可以直接渲染成图表,适合技术文档绘制流程图。

六、多语言翻译工作流:Crowdin 集成

Joplin 文档的翻译通过 Crowdin 平台完成(crowdin.yml 中 project_id: '624298',API Token 通过环境变量 CROWDIN_PERSONAL_TOKEN 提供,且 preserve_hierarchy: true 保持目录结构)。源文件为 /readme/**/*,译文输出到 /readme/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%;crowdin.yml 同时排除了新闻、API、CLI、CLA、隐私声明等不适合众包翻译的目录与二进制资源。

6.1 上传待翻译字符串

在仓库根目录执行(README 中的命令需在根目录运行,crowdinUpload 等脚本定义在根 package.json):

CROWDIN_PERSONAL_TOKEN=..... yarn crowdinUpload

crowdin upload 会把 readme/ 下待翻译的文档同步到 Crowdin 项目。翻译前还需先同步站点 UI 文案:yarn buildWebsiteTranslations 会调用 packages/tools/website/buildTranslations.ts,用 gettext-extractor 从 Assets/WebsiteAssets/templates/ 下的 front.mustache、plans.mustache 等模板中提取 [translate] 标记的文本,生成 Assets/WebsiteAssets/website.pot,再与各语言 .po 文件合并。

6.2 拉取翻译回本地

CROWDIN_PERSONAL_TOKEN=..... yarn crowdinDownload

crowdin download 将最新译文落到 readme/i18n/<语言代码>/ 下。回到第一节,processDocs.js 的 main() 会检查 readme/i18n 目录是否存在,存在则把其中的翻译文档也处理进 packages/doc-builder/i18n(processDocs.ts),从而参与 Docusaurus 的多语言构建。

6.3 新增一种语言

README 给出的步骤非常明确,完整流程是:

  1. 先在 Crowdin 中确认该语言已有可用的翻译;
  2. 在 packages/doc-builder/docusaurus.config.js 的 i18n.locales 数组中加入语言代码;
  3. 若该语言还参与首页/Plans 等 Mustache 页面的渲染,则同步在 packages/tools/website/utils/supportedLocales.ts 中登记 id / lang / pathPrefix / code / name / hreflang,并为 Assets/WebsiteAssets/locales/ 准备对应 .po 文件(build.ts 中按 supportedLocales 逐语言解析 .po 并应用翻译)。

七、生产构建与发布

文档站的生产发布由 release-website.sh 完成——该脚本在 packages/tools/release-website.sh 中可见,README 中说明其逻辑维护在 joplin/website 仓库。生产构建的本质与本地全量构建一致:以 --env prod 运行 processDocs(baseUrl: https://joplinapp.org,Docusaurus 使用 _build 即压缩产物),再执行 build.js 合并静态资源、生成 sitemap(changefreq: 'weekly')与各语言页面,最后部署到 CDN。

需要注意的生产细节:

  • 生产构建同样强依赖 joplin-website/docs 输出目录,且 processDocs 的 prod 配置会校验 baseUrl;
  • 新闻页面(News)由 updateNews.ts 按日期生成归档,readme/news/ 下文件以 YYYYMMDD-标题 命名,front matter 会被自动补上 date 字段(processDocs.ts);
  • 站点配置了 favicon、sitemap.xml、navbar(Plugins / News / Help / Forum / Joplin Cloud / 语言切换)与 dark 风格 footer,这些均可在 docusaurus.config.js 中按需调整。

八、常见问题与排错速查

现象 原因与处理
node website/processDocs.js --env dev 报 Env must be specified 忘记传 --env 参数,必须显式指定 dev 或 prod(processDocs.ts)
构建报 broken link 错误 onBrokenLinks: 'throw' 生效,检查文档内相对链接与 readme/ 目录一致性
build.js 报 docs directory does not exist 输出目录 joplin-website/docs 缺失,先创建它(build.ts)
开发服务器上搜索/重定向不生效 这些是生产插件,改用「构建 + yarn watchWebsite」验证
Crowdin 命令鉴权失败 未设置 CROWDIN_PERSONAL_TOKEN 环境变量(crowdin.yml 通过 api_token_env 读取)
新语言页面 404 检查是否同时更新了 docusaurus.config.js 的 i18n.locales 与 supportedLocales.ts

总而言之,Joplin 的文档站是一个「Markdown 单一事实来源 + Docusaurus 2 编译 + Crowdin 众包翻译 + 静态托管」的完整工程实践:内容作者只需维护 readme/ 下的 Markdown,构建工具链自动完成 MDX 转换、front matter 补全、链接重写、SEO 元信息抽取与多语言归档。理解 processDocs.ts → buildDev → watchWebsite → crowdin → release-website 这条链路,无论是为 Joplin 贡献文档、新增语言,还是自建同类文档站点,都能直接复用这套方法论。

登录后查看全文
joplin