clean-jsdoc-theme

TypeDoc 快速开始

对于 TypeScript 项目，本主题以 TypeDoc 插件 的形式发布 —— @clean-jsdoc-theme/typedoc。它并不是一个扩展 TypeDoc 默认样式的 CSS 主题；它注册了一个自定义 输出，将 TypeDoc 的 reflection 送入与 JSDoc 桥接 相同 的 setu → dwar 流水线。结果是一个完全相同的 站点 —— SSR HTML、islands、模糊 + 全文搜索、配套的 .md —— 由你的 TypeScript 源代码生成。

它是如何接入的。 该插件的 load(app) 声明了一个选项块（cleanJsdocTheme，参见 options.ts）， 并通过 app.outputs.addOutput(...) 注册了一个名为 clean-jsdoc-theme 的输出。writer (write-site.ts) 将 reflection → doclet → 共享流水线进行适配。因此你通过两种方式来选用它： plugin 负责加载它，outputs 负责开启它。

安装与构建

  1. 1
    Install

    将 TypeDoc 和本主题的 TypeDoc 插件安装为开发依赖：

    代码
    npm install --save-dev typedoc @clean-jsdoc-theme/typedoc
  2. 2
    Configure

    添加一个 typedoc.json。加载插件，将其选为一个 输出，并把主题 选项放在 cleanJsdocTheme key 下面（即 JSDoc 的 opts 在 TypeDoc 中的对应物）：

    代码
    {
  entryPoints: ["src/index.ts"],
  tsconfig: "tsconfig.json",
  readme: "README.md",

  // Load the plugin, then select its output to render.
  plugin: ["@clean-jsdoc-theme/typedoc"],
  outputs: [{ name: "clean-jsdoc-theme", path: "dist" }],

  // Theme options live here.
  cleanJsdocTheme: {
    siteName: "My Library",
  },
}
  3. 3
    Build

    运行 TypeDoc —— 它会把注册的输出渲染到 outputs[].path：

    代码
    npx typedoc
  4. 4
    Serve

    打开 dist/index.html，或者为该文件夹提供服务（Pagefind 的全文索引需要 HTTP 才能加载）：

    代码
    npx serve dist

一个完整、可运行的 TypeDoc 配置位于仓库的 examples/typedoc-basic —— 其中的 typedoc.json 是上述配置的参考。

选项放在哪里

每个主题选项都与 JSDoc 的完全相同 —— 只是位置不同：放在 cleanJsdocTheme 下面，而不是 opts。完整的列表，连同两种形式并排 展示，都在 Configuration 页面上。先从这几个开始：

Option它的作用
siteName页头标题 —— 纯文本，或一组带 alt 后备文本的 light/dark logo。
fonts覆盖 heading / body（Google Fonts，已为你加载）以及 mono。
colors / darkColors重新着色 light / dark 调色板 —— 仅覆盖 bg、accent……，其余保持不变。
menu固定在 sidebar 上方的自定义链接，每个都带一个 lucide: / simpleicons: 图标。
docGroups排定 sidebar 中 prose doc groups 的顺序（API 区块是 module 层级结构）。
copyPage每页的 "copy page" / "open in LLM" 按钮（默认开启）。

由于 cleanJsdocTheme 是一个专用的 namespace，其中未知的 key 只会 warn（并附带一条 "did you mean?" 提示）—— 参见 strict 以将其升级为 error。

The TypeDoc sidebar

TypeDoc 输出的侧边栏不使用 JSDoc 模板的 kind-bucket 布局（顶层的 "Classes"、"Interfaces"、"Enumerations" 等区块）。相反，它镜像的是 TypeDoc 自身的默认主题 —— 一种 module/folder 层级结构：

  • 顶层 = 你的 documents 在前，然后是 folders 和 modules，按字母顺序排列。 没有顶层的 kind sections。
  • Folders 来自你源代码的目录结构。只有单个 child 的 folder 会被 合并进那个 child（compactFolders）—— 例如 base/ 下的单个 Component 会显示为 base/Component，而不是两层嵌套。
  • 每个 module 都是一个可点击、可展开的节点：点击其 label 会打开该 module 自己的页面；chevron 展开后会显示它的成员。
  • 成员嵌套在其所属的 module 下，按 kind 排序 —— Enumerations → Classes → Interfaces → Type Aliases → Variables → Functions —— 然后按 字母顺序排名称。侧边栏本身没有按 kind 划分的子标题（kind 分组仍会出现在 该 module 自己的页面正文中）。
  • 嵌套在某个 module 内的 Namespaces 会以同样的方式呈现为嵌套节点。

这是一种与 JSDoc 模板不同的侧边栏模型。在 Structure your sidebar 中记录的排序 杠杆 —— @category、@order、sectionOrder、clubSidebarItems —— 不会 影响 TypeDoc 的 API 侧边栏。上面描述的 module 层级结构掌管着它，与 TypeDoc 自身的默认行为一致（其中由 category/group 驱动的导航是可选启用的）。 恢复一个由 category/group 驱动的 TypeDoc 导航，目前尚不可配置。

对 TypeDoc 仍然有效的：正文的doc groups（docGroups + 文档页面 frontmatter 中的 group / order）仍会渲染 —— 在 API 层级结构之前 —— 并通过 docGroups 排序；menu 顶部区域仍然有效；tutorials 仍会渲染。 完整细节见 Structure your sidebar。

TypeDoc-specific rendering

除了侧边栏之外，TypeDoc 输出还会渲染一些 JSDoc 模板不会渲染的内容， 因为它们来自 TypeDoc 自身的分析：

  • 继承与关系。 Class 和 interface 页面会获得一个 Hierarchy 列表 （祖先链）、一个 Implements section，以及一个 Implemented By section。各个成员会获得说明性文字 —— Inherited from …、 Overrides …、Implementation of … —— 指向相关的 symbol。

  • @group。 被识别为 @category 的同类标签。它会被解析，但 —— 与 @category 一样 —— 它不会驱动 TypeDoc 的默认侧边栏（见上文）。

  • 原生 TypeDoc projectDocuments。 通过 TypeDoc 自身的 projectDocuments 选项附加的 Markdown 文件会渲染为页面。这与本主题自己的 docs 选项不同：

    • docs 是本主题的正文文档目录 —— 它对 JSDoc 和 TypeDoc 的工作方式相同。
    • projectDocuments 是 TypeDoc 原生的输入，只有 TypeDoc 输出可用。

    两者最终都会变成站点中普通的页面，因此请根据你想让哪个工具掌管 文件列表来做选择：如果想要一个共享、与工具无关的 guides 文件夹， 用 docs；如果你已经按 TypeDoc 原生的方式组织文档，用 projectDocuments。

  • @inheritDoc。 用 @inheritDoc Target（或在一个 overriding/ implementing 成员上单独写 @inheritDoc）记录文档的成员，会在其位置 显示目标的 description 以及 parameter/return 文档。TypeDoc 会解析该 引用；本主题渲染其结果内容 —— 与 TypeDoc 默认语义保持一致。

  • Async 修饰符徽章。 是 async（或返回 Promise）的方法，会在其 签名旁显示一个 async 修饰符徽章。

  • Object-literal 类型展开。 一个内联的 object-literal 类型 —— 出现在 参数、返回类型，或一个类型别名/变量上 —— 会展开成一个属性表：每个 成员一行，包含名称、类型、可选标记和描述。表格中的类型引用仍会保持 链接到其对应的文档页面。

多语言

localization 工作流在同一个 cleanJsdocTheme 块中声明它的 locale （locales + defaultLocale），并通过 clean-jsdoc CLI 运行 —— 参见 Localize your docs 以及 locales / defaultLocale 参考。

目前 TypeDoc 桥接可以 extract 翻译目录，但还不能渲染各个 locale 的 站点 —— 本地化的 构建 暂时只支持 JSDoc。单语言的 TypeDoc 站点已获得 完整支持。

后续步骤