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 插件安装为开发依赖：

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

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

    CODE
    {
  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：

    CODE
    npx typedoc
  4. 4
    Serve

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

    CODE
    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……，其余保持不变。
sectionOrder排定顶层 sidebar 区块的顺序。
clubSidebarItems将相关条目收拢到一个共享的、可折叠的父项之下。
menu固定在 sidebar 上方的自定义链接，每个都带一个 lucide: / simpleicons: 图标。
copyPage每页的 "copy page" / "open in LLM" 按钮（默认开启）。

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

多语言

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

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

后续步骤