Typedoc

@clean-jsdoc-theme/typedoc — working skill

<!-- skill-revision: 2026-07-02 -->

This skill makes you an expert at using clean-jsdoc-theme v5 with TypeDoc, via the @clean-jsdoc-theme/typedoc plugin. Everything here is verified against the plugin source (packages/typedoc/). It is focused: it owns the TypeDoc-only material and defers to the umbrella skill for everything JSDoc and TypeDoc share.

Read the umbrella skill for shared topics. Authoring (callouts, steps, tabs, embeds, custom tags), images / static assets, the full option table, and theming behave the same on both toolchains. Don't duplicate that knowledge here — read it from the sibling clean-jsdoc-theme skill:

Shared topic	File
The full option reference (all options, both namespaces)	../clean-jsdoc-theme/reference/configuration.md
Authoring: callouts, steps, tabs, embeds, @iframe, playground	../clean-jsdoc-theme/reference/authoring.md
Images / local assets / sitemap	../clean-jsdoc-theme/reference/images.md
Docs directory, frontmatter, cross-links	../clean-jsdoc-theme/reference/content-and-sidebar.md
The package architecture	../clean-jsdoc-theme/reference/architecture.md

The TypeDoc-only deep dive — the sidebar model, the document model, and the rendering TypeDoc adds — lives in the sibling reference:

Project: https://github.com/ankitskvmdam/clean-jsdoc-theme · npm: @clean-jsdoc-theme/typedoc · verified against TypeDoc 0.28.x.

1. What it actually is

The TypeDoc integration is not a CSS theme extending TypeDoc's DefaultTheme. It is a plugin that registers a custom output. It feeds TypeDoc's reflection tree through the same setu → dwar pipeline as the JSDoc bridge, so a TypeScript project gets an identical site — SSR HTML, lazy-hydrated Preact islands, fuzzy search, and a companion .md per page for LLMs.

TypeDoc reflections ──▶ reflection-to-doclets ──▶ setu.generateSite('typedoc')
                                                    ──▶ dwar.render() ──▶ static site

You select it two ways, and you need both:

• plugin loads the plugin (its load(app) declares the option block and calls app.outputs.addOutput('clean-jsdoc-theme', …)).
• outputs turns it on (the entry whose name is "clean-jsdoc-theme" runs the writer, rendering to that entry's path).

Loading the plugin alone renders nothing — a common first mistake (see §5).

The plugin is ESM, and typedoc is a peer dependency — you bring your own TypeDoc.

2. Setup

npm install --save-dev typedoc @clean-jsdoc-theme/typedoc

// typedoc.json
{
  entryPoints: ["src/index.ts"],
  tsconfig: "tsconfig.json",
  readme: "README.md",                                     // ← TypeDoc's OWN option (see below)

  plugin: ["@clean-jsdoc-theme/typedoc"],                  // loads it
  outputs: [{ name: "clean-jsdoc-theme", path: "dist" }],  // turns it on

  cleanJsdocTheme: {                                       // ← theme options live here
    siteName: "My Library",
  },
}

Build, then serve over HTTP (the island chunks and the search index are fetched, which file:// blocks):

npx typedoc
npx serve dist

Runnable reference: examples/typedoc-basic in the repo — its typedoc.json is the canonical setup.

readme is TypeDoc's own top-level option, not a theme option. The home page comes from TypeDoc's readme (rendered from project.readme), or a root docs/index.md in the theme's docs directory overrides it. Both readme and cleanJsdocTheme sit at the top level of typedoc.json.

3. Options: same names, one namespace, a few gaps

Theme options use the same names and values as JSDoc's opts — just nested under cleanJsdocTheme instead of opts. The full table (both namespaces side by side) is in the umbrella skill's configuration.md.

Because cleanJsdocTheme is a dedicated namespace, unknown keys inside it always warn (with a "did you mean?" hint) and the build continues; set strict: true to escalate to a hard error.

What the TypeDoc writer actually wires (verified)

The blanket "every option works the same" is almost true — but a few options are validated yet not yet applied by the TypeDoc writer. Be precise here; this is the skill's whole value.

Fully wired for TypeDoc:

• Identity/fonts: siteName (text or logo set), fonts (incl. per-locale keys), favicon
• Content: docs, docGroups, defaultDocGroup (+ native projectDocuments, see the deep dive)
• Sidebar: menu, sectionOrder, clubSidebarItems (accepted/validated — but the module hierarchy owns the API sidebar; see the deep dive for what these actually affect), collapsibleSidebarSections (this one does apply — collapsible top-level section headers; both flavors)
• LLM/pager: copyPage, pageNav, aiPrompt, playground
• Chrome/meta: footer (string or { file }), meta
• Deploy: basePath (sub-directory hosting — every asset href is prefixed), siteUrl (emits sitemap.xml; TypeDoc's own hostedBaseUrl is used as a fallback, and cleanJsdocTheme.siteUrl wins if both are set), llmsTxt (emits llms.txt + llms-full.txt; needs a site URL)
• Build: strict

NOT wired through the TypeDoc writer today (they validate but have no effect — don't promise them):

• colors / darkColors — the palette is the built-in OKLCH default. Only fonts and siteName affect appearance; custom colors are a known gap.
• customCss / customJs / customCssFile / customJsFile / hashCustomAssets — not threaded.
• locales / defaultLocale — the localized build is JSDoc-only (see §4).
• tutorials — a JSDoc --tutorials concept; use docs or projectDocuments for prose.

templates.default.* does not exist for TypeDoc. The JSDoc-only options outputSourceFiles, sourceLinkToComment, and staticFiles live under JSDoc's templates.default — there is no equivalent in typedoc.json. Source-file viewer pages and Source: file:line links still work for TypeDoc (they're generated unconditionally from reflection source metadata) — they're just not toggleable, and always land on the declaration.