Clean Jsdoc Theme

clean-jsdoc-theme — working skill

<!-- skill-revision: 2026-06-26 -->

This skill makes you an expert at using and extending clean-jsdoc-theme v5. Everything here is verified against the source. When a user is documenting a JS/TS project with this theme, configuring it, authoring prose, or hacking on the packages, follow this over your prior assumptions about "a JSDoc theme."

This file is the operating guide: the mental model, setup, and behaviour. The detailed reference lives in sibling files under reference/ — read the one that matches the task (don't load them all):

Skill revision: 2026-06-26. Versioned with the theme — see §6 Staying current for how (and how often) to check for a newer skill or theme release.

Project: https://github.com/ankitskvmdam/clean-jsdoc-theme · npm: clean-jsdoc-theme (JSDoc) and @clean-jsdoc-theme/typedoc (TypeDoc).

1. What it actually is (mental model)

clean-jsdoc-theme is not a CSS skin on JSDoc's default template. It is a complete documentation pipeline. JSDoc or TypeDoc is used only to collect doc comments; from there the theme builds its own structured model and renders a modern static site.

The pipeline is one-way and shared by both entry points:

JSDoc doclets  ─┐
                ├─▶  setu.generateSite()  ─▶  SiteManifest  ─▶  dwar.render()  ─▶  static site
TypeDoc reflns ─┘        (no I/O)                                 (pure, uses rang components)

render() emits, per build: ‹slug›/index.html per page (SSR + lazy-hydrated Preact islands, only the islands a page uses); ‹slug›/index.md per content page (a companion Markdown authored for LLMs — the theme's defining feature); _assets/styles.‹buildId›.css; _assets/search-index.‹buildId›.json (the Ctrl K fuzzy index); and _islands/‹name›.js.

Guarantees worth knowing: setu does no disk I/O (the bridge reads files), dwar.render() is pure, and one page that fails to compile is skipped and reported, never aborts the build.

2. Setup

Two entry points. Pick the one matching the toolchain. The option names and values are identical between them — only where you put them differs: JSDoc uses opts, TypeDoc uses a cleanJsdocTheme block. (Full option list: reference/configuration.md.)

JSDoc

npm install --save-dev jsdoc clean-jsdoc-theme

// jsdoc.json
{
  source: { include: ["./src", "./README.md"] },
  plugins: ["plugins/markdown"],          // REQUIRED — see note below
  opts: {
    template: "node_modules/clean-jsdoc-theme/dist",
    destination: "dist",
    recurse: true,
    readme: "./README.md",
    siteName: "My Library",               // ← theme options live under opts
  },
}

Build: npx jsdoc -c jsdoc.json → dist/. Serve with npx serve dist (the island chunks and the search index are fetched, so opening index.html from disk leaves search and the islands dead).

Required: the plugins/markdown plugin. JSDoc renders comment Markdown → HTML before the theme sees it, and the theme consumes that HTML. Without it, descriptions arrive as raw, unformatted text.

TypeDoc

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

// typedoc.json
{
  entryPoints: ["src/index.ts"],
  tsconfig: "tsconfig.json",
  readme: "README.md",
  plugin: ["@clean-jsdoc-theme/typedoc"],            // loads it
  outputs: [{ name: "clean-jsdoc-theme", path: "dist" }],  // turns it on
  cleanJsdocTheme: { siteName: "My Library" },       // ← theme options live here
}

It registers a custom output (not a CSS theme extending DefaultTheme). Build with npx typedoc. Runnable references in the repo: examples/basic (JSDoc), examples/typedoc-basic (TypeDoc), docs-site/ (a prose-first dogfood site).

3. What becomes a page

A class page leads with the class description (classdesc), then a Constructor section (on every class unless @hideconstructor): the call signature (new ClassName(id, [opts]) — a parameter-less class still shows new ClassName(), and an undocumented constructor recovers its param names so new ClassName(options) still appears), the separately-documented constructor description (when the class and its constructor have separate doc comments), and the parameter table. Every member/constructor heading now also shows the full TypeScript signature (addChild(child: Component): void), highlighted inline (both JSDoc and TypeDoc).

TypeDoc projects render a slightly different document model (v5.0.x parity with default TypeDoc — automatic, no config): enums, top-level functions, and variables each become a standalone page (not member sections), type aliases are labelled "Type Aliases", class sections use TypeDoc labels (Constructors / Properties / Accessors / Methods), module/namespace pages are a kind-grouped index of links to their exports, generics get a Type Parameters section, and overloaded functions stack one signature per overload. Standalone pages lead with a full declaration block. JSDoc's model (above) is unchanged.

4. Quick reference

// JSDoc: opts.* | TypeDoc: cleanJsdocTheme.*  (identical values)
{
  siteName, basePath, siteUrl, llmsTxt, favicon,
  readme, docs, docGroups, defaultDocGroup, tutorials,
  sectionOrder, clubSidebarItems, collapsibleSidebarSections, menu,
  fonts, colors, darkColors, scrollbar,
  customCss, customJs, customCssFile, customJsFile, hashCustomAssets,
  footer, meta, playground,
  copyPage, aiPrompt,
  locales, defaultLocale,        // multi-language — see reference/localization.md
  strict, progress
}
// JSDoc-only, under templates.default.*:  outputSourceFiles, sourceLinkToComment, staticFiles

Authoring (details in reference/authoring.md):

• Callout: > [!TIP] / [!NOTE] / [!WARNING] / [!ERROR] (+ aliases).
• Steps: <steps><step label="…">…blank-line-wrapped body…</step></steps>.
• Tabs: <tabs group="x"><tab label="…" value="…">…</tab></tabs>.
• Embed: ```iframe fence or @iframe <https-url> key=value.
• Sidebar: @category Core/Parsing order=1, @order N, frontmatter group/order.
• Cross-link: {@link Symbol}, {@linkcode Symbol}, @see {@link Other}.
• Images: ![alt](./img/x.svg) from docs/tutorials/README/doc comments → copied to _assets/ (SVGs inlined, theme-aware); JSDoc staticFiles bare names resolve too (reference/images.md).

The two most common setup mistakes: missing plugins/markdown (JSDoc) and missing tags.allowUnknownTags: true (needed for @category/@order/@iframe). More in reference/troubleshooting.md.