Wasp 文档写作规范详解分区决策准则与 auto-js、with-hole、fix-api-links 定制 Docusaurus 插件【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp本篇技术文章基于 Wasp 仓库中的 文档写作指南讲解该官方文档站Docusaurus 构建的内容组织原则与代码示例编写机制包括各文档分区Essentials、Data Model、Advanced Features 等的归类决策标准以及auto-jsTypeScript 自动生成 JavaScript 版本、with-hole代码省略号、fix-api-linksAPI 文档链接重写三个 remark 插件的用法与底层实现。读完本文你能在 Wasp 文档中正确放置新页面、编写自动双语言代码块并理解这些定制插件在 Docusaurus 配置 中的注册方式与 AST 转换原理。文档格式与目录组织Wasp 的文档可以使用Markdown 或 MDX编写统一位于仓库的 web/docs 目录下。站点由 Docusaurus 构建配置入口为 web/docusaurus.config.ts侧边栏结构定义在 web/sidebars.ts。当你要新增一个页面时写作指南要求先阅读分区准则来确定页面归属如果新页面需要一个全新的分区则要把该分区补充进指南文档本身并附上“如何判断一个页面是否属于该分区”的决策信息。下面完整继承并展开原文档定义的六个分区。Getting StartedWasp 是什么如何获得它回答“什么是 Wasp、如何获取”这一类问题。该分区对应侧边栏中的 Getting Started 类目web/sidebars.ts 中的introduction/introduction、introduction/quick-start、introduction/editor-setup等页面。Essentials拿到 Wasp 之后能做什么解释 Wasp 的工作流与最重要的部分覆盖四类核心问题如何创建一个新项目项目里包含什么目录结构如何给网站添加更多页面如何把数据存到数据库。归属判据一个特性属于 Essentials当且仅当它是核心特性——几乎每个 Wasp 项目都会以某种形式用到它。Data Model如何在 Wasp 中持久化数据归属判据看特性的宏观目的。只要答案里涉及“数据”或“数据库”大概率应放在这里。原文档还专门解释了它与 Essentials 的边界数据模型是 Wasp 的核心组成部分之所以独立成区是因为其中有些部分是“extras”——不同项目按需选用如迁移工具、种子数据等并非每个项目都会完整用到与 Essentials“每个项目都用”的标准不同。Advanced FeaturesWasp 还能提供什么归属判据两条同时满足它不是核心特性不满足 Essentials 标准它是单一概念“单元”——即该特性没有多个复杂子组件。原文档给出的反例正是认证auth 有多个 provider每个 provider 的用法与配置差异很大需要长篇解释因此不适合塞进 Advanced Features。Authentication认证的全部选项回答“我知道 Wasp 有 auth现在告诉我所有选项”。独立成区的原因与上面相对auth 各 provider 在使用方式与配置上差异显著auth UI 本身也是个大话题再加上认证使用的最佳实践体量足以单独分区。Project Setup如何在我的项目里添加/配置 X回答“如何在我的项目中添加或配置 X”这类操作型问题。原文档解释了为什么它们不算 Advanced Features这些条目“又无聊又小”本身不是 Wasp 的有趣特性只是“可以做到的事情”且都与项目配置/项目内可以存在什么相关。代码块示例两个自定义 Docusaurus 插件写作指南指出Wasp 团队创建了几个自定义 Docusaurus 插件来让代码块编写更简单、更一致。它们以 remark 插件的形式在 web/docusaurus.config.ts 中注册remarkPlugins: [ autoJSCode, autoImportTabs, fileExtSwitcher, searchAndReplace, codeWithHole, fixAPILinks, ],注意注册顺序autoJSCode排在最前codeWithHole在其后这与两个插件的可组合性直接相关见下文with-hole一节。auto-js只写 TypeScript自动生成 JavaScript 版本对于需要同时提供 JavaScript 与 TypeScript 两个版本的示例只需编写 TypeScript 版本并在代码块 meta 中加上auto-js标记ts titlesrc/apis.ts auto-js export const validatePassword (password: string) password.length 8; 构建时它会被自动转换成带标签页切换器的 MDX 结构——ts-blank-space剥离类型注解生成 JS 版本并自动为两个版本加上切换 TabTabs groupIdjs-ts TabItem valuejs labelJavaScript js titlesrc/apis.js export const validatePassword (password) password.length 8; /TabItem TabItem valuets labelTypeScript ts titlesrc/apis.ts export const validatePassword (password: string) password.length 8; /TabItem /Tabs该插件的完整实现在 web/src/remark/auto-js-code.ts。结合源码可以看到几条原文档未展开的实现细节语言映射插件只支持ts - js与tsx - jsx两种转换源码中LANGUAGE_TRANSFORMATIONS常量auto-js-code.ts#L59-L62title中的文件扩展名会同步替换.ts - .js、.tsx - .jsx。Wasp Spec 文件的限制如果代码块title匹配*.wasp.ts(x)插件会直接抛错并终止构建——源码注释表明 Wasp Spec 文件“应当始终是 TypeScript”不存在 JS 版本auto-js-code.ts#L165-L170。转换管线先用ts.createSourceFile在内存中创建 TS 源码文件根据语言选择ScriptKind.TS或TSX再调用blankSourceFile剥离类型最后用 Prettier 的babel/babel-tsparser 分别格式化生成的 JS 与原始 TS 代码块auto-js-code.ts#L203-L217。错误处理任何一步抛错都会被file.fail记录为带代码块位置信息的构建错误而不是静默跳过。auto-js 的已知注意事项Caveatsauto-js底层依赖 ts-blank-space——注意原文档引用的该库外部链接在本文按规范不再保留外部站址此处仅说明其作用它只移除类型注解不处理其他任何语法。因此存在一些边界情况写作指南推荐跑npm run start并在浏览器中检查生成的 JS 输出是否正常。已知注意事项包括Prettier 重排由于 TS→JS 转换的机制auto-js会对你的代码执行prettier格式化。建议把生成的代码复制回源文件保证“写法”与“展示”一致。类型专用 import 不会删除仅导入类型的import语句不会从生成的 JS 中移除除非你在 import 中使用type说明符如import type { X } from ...。高亮注释错位TS 专属行前的// highlight-next-line注释转换后该行被删掉但注释残留会高亮到错误的一行。应改用// highlight-start/// highlight-end成对注释。文件名不会被替换插件不会替换代码块内部的文件名引用例如 import 路径或说明性注释。这主要影响教程页面教程中文件扩展名是动态切换的目前尚无解决方案。如果以上任何一条妨碍你正确表达代码写作指南建议直接手写 JS 版本见下一节——auto-js只是避免写两遍代码的便利设施。手动创建语言切换器不想依赖auto-js时可以按 Docusaurus 官方的“多语言代码块”multi-language code blocks特性手工编写Tabs/TabItem结构。这也是所有auto-js生成结果的目标形态——理解手写方式有助于排查自动生成失败时的降级方案。with-hole在代码示例中省略部分代码当示例需要省略部分代码时with-holemeta 属性会把代码块中你写的$HOLE$标识符替换为省略号同时保持代码语法合法。它可与auto-js组合使用。示例输入ts titlesrc/apis.ts auto-js with-hole export const validatePassword (password: string) password.length 8 $HOLE$; 转换结果两个语言版本各自独立替换且 JS 版本由去类型后的 TS 代码生成Tabs groupIdjs-ts TabItem valuejs labelJavaScript js titlesrc/apis.js export const validatePassword (password) password.length 8 /* ... */; /TabItem TabItem valuets labelTypeScript ts titlesrc/apis.ts export const validatePassword (password: string) password.length 8 /* ... */; /TabItem /Tabs实现在 web/src/remark/code-with-hole.ts核心逻辑非常直接const META_FLAG with-hole; const HOLE_IDENTIFIER $HOLE$; const HOLE_REPLACEMENT /* ... */; const SUPPORTED_LANGS [js, jsx, ts, tsx] as const; // ... node.value node.value.replaceAll(HOLE_IDENTIFIER, HOLE_REPLACEMENT);从源码可以确认两点细节替换的目标是块注释/* ... */而非裸的...这样在表达式位置省略时依然语法合法auto-js的类型剥离也不会受影响支持语言限定为js、jsx、ts、tsx代码块语言不在其中会通过assertCodeBlockIsInLanguage报错该工具函数定义在 web/src/remark/util/code-blocks.ts。在配置中的注册顺序codeWithHole位于autoJSCode之后意味着with-hole的替换发生在auto-js的 TS→JS 转换之前所以$HOLE$会先变成/* ... */再被ts-blank-space一并转换两个 Tab 中都能看到省略号。链接fix-api-plugins 与 API 文档的双上下文链接fix-api-links把 wasp.sh 绝对 URL 重写为相对链接Wasp 站点的 API 参考docs/api/由wasp.sh/spec包源码中的TSDoc 注释自动生成见 spec 包 README。这些注释同时被站点外部作为原始 markdown 消费例如作为 IDE 注释因此注释中的链接必须同时在两种上下文里有效。为此作者需要在 TSDoc 注释中以完整的https://wasp.sh/docs/...绝对 URL 形式书写指向其他 Wasp 文档的链接fix-api-links插件则在构建时剥掉https://wasp.sh前缀只保留相对路径——相对链接在站点上可以正常解析而且可以接受断链检查。实现在 web/src/remark/fix-api-links.ts全部逻辑只有几行但从源码可以精确读出它的触发条件与作用范围const API_FOLDER docs/api/; const URL_PREFIX https://wasp.sh; const fixAPILinks: Plugin[], md.Root () (tree, file) { const relativePath path.relative(file.cwd, file.path); if (!relativePath.startsWith(API_FOLDER)) return; // 只处理 docs/api/ 下的文件 visit(tree, link, (node) { if (node.url.startsWith(URL_PREFIX)) { node.url node.url.slice(URL_PREFIX.length); // 剥掉前缀 } }); };两个关键约束仅对docs/api/目录内的 markdown 生效——其他文档即使写了 wasp.sh 绝对链接也不会被重写写作时在正文中仍应使用仓库内相对路径只有以https://wasp.sh开头的链接 URL 会被改写改写成相对路径后即可被断链工具检查。这一点与全局配置相呼应web/docusaurus.config.ts 中设置了onBrokenLinks: throw与onBrokenAnchors: throw即任何断链/断锚都会使构建直接失败。所以 API 文档“先写绝对链接、构建时重写为相对链接”的设计正是为了让生成文档既能通过构建期断链检查又能在 TSDoc 的原始消费场景下保持有效。写作检查清单综合指南与配置提交文档前应验证页面归属新页面是否按六分区的决策标准放对了位置若是新分区是否已把分区及判断标准补进 web/WRITING-DOCS.md 并更新 web/sidebars.ts。auto-js 输出对使用auto-js的代码块运行npm run start在浏览器中检查生成的 JS 是否符合预期类型 import、高亮注释、文件名引用是三大易错点。省略号用法需要省略代码时用$HOLE$with-hole而不是手工敲...裸...在表达式中可能破坏语法也会干扰auto-js的类型剥离。API 文档链接在wasp.sh/spec的 TSDoc 中写完整https://wasp.sh/docs/...链接交给fix-api-links重写正文文档则使用仓库内相对路径最终由onBrokenLinks: throw兜底把关。以上机制的完整代码分布在 web/src/remark 目录下auto-js-code.ts、code-with-hole.ts、fix-api-links.ts及其共享工具 web/src/remark/util/code-blocks.ts所有插件均通过 web/docusaurus.config.ts 的remarkPlugins列表统一注册可按同样方式为文档流水线扩展更多 markdown 转换能力。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考