clean-jsdoc-theme

JSDoc 快速开始

clean-jsdoc-theme 是一个 JSDoc template。JSDoc 做它一贯做的事 —— 解析你的 source 并收集你的 doc comments —— 然后把控制权交给 template 的 publish function，主题正是从这里接手并构建静态站点。你只需将 JSDoc 指向 该主题，就大功告成了。

它是如何接入的。 JSDoc 通过调用 template 导出的 publish function 来 加载它 —— 在这里就是 publish(data, opts, tutorials) （即 package 的 main，dist/publish.js）。它接收你的 doclet collection， 并将其送入 setu → dwar pipeline。关于每个阶段各自的作用，请参阅 Packages。

安装与构建

  1. 1
    Install

    将 JSDoc 和主题安装为 dev dependencies：

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

    在你的 project root 中添加一个 jsdoc.json。一个虽小但贴近实际的起点：

    CODE
    {
  source: { include: ["./src", "./README.md"] },

  // 必需 —— 请参阅下方警告。
  plugins: ["plugins/markdown"],

  opts: {
    // 将 JSDoc 指向主题。等同于 CLI 上的 `jsdoc -t <path>`。
    template: "node_modules/clean-jsdoc-theme/dist",
    destination: "dist",
    recurse: true,
    readme: "./README.md",
    siteName: "My Library",
  },
}

    plugins/markdown plugin 是必需的。在主题看到之前，JSDoc 就已经把你 doc comments 中的 Markdown 渲染为 HTML，而主题消费的正是该 HTML（参见 from-html.ts）。 缺少它，descriptions 会以原始、未格式化的 text 形式到达。

  3. 3
    Build

    针对该配置运行 JSDoc：

    CODE
    npx jsdoc -c jsdoc.json
  4. 4
    Serve

    站点会被写入 dist/。打开 dist/index.html，或者将该文件夹作为服务提供 （Pagefind 的全文索引需要 HTTP 才能加载）：

    CODE
    npx serve dist

一个完整、可运行的 JSDoc setup 位于仓库的 examples/basic —— 它的 jsdoc.json 和 source comments 是本页所有内容的参考。

选项放在哪里

主题选项位于 jsdoc.json 中的 opts 之下，与 JSDoc 自身的选项并列。 下面是你最先会用到的几个 —— 完整列表（并排展示 TypeDoc 形式）见 Configuration 页面。

Option它的作用
siteNameHeader 标题 —— 纯 text，或一组带 alt 后备文本的 light/dark logo。
fonts覆盖 heading / body（Google Fonts，会为你加载）和 mono。
colors / darkColors重新为 light / dark 调色板着色 —— 只覆盖 bg、accent、…，其余保持不变。
sectionOrder排定顶层 sidebar sections 的顺序。
clubSidebarItems将相关条目归拢到一个共享的、可折叠的 parent 之下。
menu固定在 sidebar 上方的自定义 links，每个都带一个 lucide: / simpleicons: icon。
tutorials / docs将手写的 Markdown guides 与生成的 reference 并排渲染。
copyPage每个页面的 "copy page" / "open in LLM" 按钮（默认开启）。

有几个选项 —— outputSourceFiles 和 sourceLinkToComment —— 仅属于 JSDoc， 它们位于 templates.default 之下，而非 opts（主题从 jsdoc/env 中读取它们）。它们在 Configuration 页面上有标注。

多语言

主题可以将你的 docs 渲染为多种语言 —— 每个 locale 一个静态站点 （默认语言位于根目录，其余位于 /<locale> 之下），并带有一个 header 语言切换器。你在 opts.locales 中声明这些 locale，然后用 clean-jsdoc CLI 驱动翻译与各 locale 的构建：

CODE
opts: {
  locales: [
    { code: "en", name: "English" },
    { code: "ja", name: "日本語" },
  ],
  defaultLocale: "en",
}

没有 locales 的构建不受影响。完整工作流（extract → translate → build）请参阅 Localize your docs，以及 locales / defaultLocale 参考。

后续步骤