clean-jsdoc-theme

TypeDoc で始める

TypeScript projects 向けに、theme は TypeDoc plugin として ship されます — @clean-jsdoc-theme/typedoc。これは TypeDoc の default を拡張する CSS theme では ありません。custom な output を register し、TypeDoc の reflections を JSDoc bridge と 同じ setu → dwar pipeline に通します。その結果、あなたの TypeScript sources から、同一の site — SSR HTML、islands、fuzzy + full-text search、companion .md — が生成されます。

どう組み込まれるか。 plugin の load(app) は 1 つの option block (cleanJsdocTheme、参照: options.ts) を宣言し、app.outputs.addOutput(...) を介して clean-jsdoc-theme という名前の output を register します。writer (write-site.ts) が reflections → doclets → 共有 pipeline へと適合させます。つまり 2 通りの方法で 選択します: plugin がそれを load し、outputs がそれを有効にします。

Install と build

  1. 1
    Install

    TypeDoc と theme の TypeDoc plugin を dev dependencies として install します:

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

    typedoc.json を追加します。plugin を load し、それを output として選択し、 theme options を cleanJsdocTheme key の下に置きます (JSDoc の opts に対応 する TypeDoc の対応物です):

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

  // plugin を load し、それから render する output を選択します。
  plugin: ["@clean-jsdoc-theme/typedoc"],
  outputs: [{ name: "clean-jsdoc-theme", path: "dist" }],

  // Theme options はここに置きます。
  cleanJsdocTheme: {
    siteName: "My Library",
  },
}
  3. 3
    Build

    TypeDoc を実行します。register された output を outputs[].path に render します:

    CODE
    npx typedoc
  4. 4
    Serve

    dist/index.html を開くか、folder を serve します (Pagefind の full-text index は load に HTTP を必要とします):

    CODE
    npx serve dist

完全で実行可能な TypeDoc setup が repo の examples/typedoc-basic にあります。その typedoc.json が上記 setup の reference です。

options はどこに置くか

すべての theme option は JSDoc 用のものと同じです。異なるのは場所だけで、opts ではなく cleanJsdocTheme の下に置かれます。完全な一覧は、両方の形式を並べて Configuration page にあります。手始めにいくつかを挙げます:

Option役割
siteNameHeader の title — プレーンテキスト、または alt fallback text を伴う light/dark の logo セット。
fontsheading / body (Google Fonts、あなたのために load されます) と mono を override します。
colors / darkColorslight / dark palettes を塗り替えます。bg、accent … だけを override し、残りはそのままにします。
sectionOrdertop-level の sidebar sections の順序を決めます。
clubSidebarItems関連する entries を共有の collapsible parent の下にまとめます。
menusidebar の上に pin される custom links。それぞれに lucide: / simpleicons: icon を付けられます。
copyPagepage ごとの "copy page" / "open in LLM" button (デフォルトで on)。

cleanJsdocTheme は専用の namespace であるため、その中の未知の keys は常に warn するだけです ("did you mean?" のヒント付き)。これを error に格上げする には strict を参照してください。

複数言語

localization workflow は、その locales を同じ cleanJsdocTheme block 内で宣言し (locales + defaultLocale)、clean-jsdoc CLI を通じて実行します。 Localize your docs と locales / defaultLocale reference を参照 してください。

現在、TypeDoc bridge は translation catalogs を extract できますが、 per-locale sites はまだ render しません。localized な builds は今のところ JSDoc 専用です。単一言語の TypeDoc site は完全にサポートされています。

次のステップ