clean-jsdoc-theme

JSDoc Getting Started

clean-jsdoc-theme is a JSDoc template. JSDoc does what it always does — parse your source and collect your doc comments — and then hands off to the template's publish function, which is where this theme takes over and builds the static site. You point JSDoc at the theme, and you're done.

How it plugs in. JSDoc loads a template by calling its exported publish function — here that's publish(data, opts, tutorials) (the package's main, dist/publish.js). It receives your doclet collection and feeds it through the setu → dwar pipeline. See Packages for what each stage does.

Install and build

  1. 1
    Install

    Install JSDoc and the theme as dev dependencies:

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

    Add a jsdoc.json to your project root. A small but real-world starting point:

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

  // Required — see the warning below.
  plugins: ["plugins/markdown"],

  opts: {
    // Point JSDoc at the theme. Equivalent to `jsdoc -t <path>` on the CLI.
    template: "node_modules/clean-jsdoc-theme/dist",
    destination: "dist",
    recurse: true,
    readme: "./README.md",
    siteName: "My Library",
  },
}

    The plugins/markdown plugin is required. JSDoc renders the Markdown in your doc comments to HTML before the theme ever sees it, and the theme consumes that HTML (see from-html.ts). Without it, descriptions arrive as raw, unformatted text.

  3. 3
    Build

    Run JSDoc against the config:

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

    The site is written to dist/. Open dist/index.html, or serve the folder (Pagefind's full-text index needs HTTP to load):

    CODE
    npx serve dist

A complete, runnable JSDoc setup lives in the repo at examples/basic — its jsdoc.json and source comments are the reference for everything on this page.

Where the options go

Theme options live under opts in jsdoc.json, alongside JSDoc's own options. A few you'll reach for first — the full list, with the TypeDoc form shown side by side, is on the Configuration page.

OptionWhat it does
siteNameHeader title — plain text, or a light/dark logo set with alt fallback text.
fontsOverride heading / body (Google Fonts, loaded for you) and mono.
colors / darkColorsRecolor the light / dark palettes — override just bg, accent, …, keep the rest.
sectionOrderOrder the top-level sidebar sections.
clubSidebarItemsCollapse related entries under a shared, collapsible parent.
menuCustom links pinned above the sidebar, each with a lucide: / simpleicons: icon.
tutorials / docsRender hand-written Markdown guides beside the generated reference.
copyPageThe per-page "copy page" / "open in LLM" button (on by default).

A couple of options — outputSourceFiles and sourceLinkToComment — are JSDoc-only and sit under templates.default, not opts (the theme reads them from jsdoc/env). They're flagged on the Configuration page.

Multiple languages

The theme can render your docs in several languages — one static site per locale (the default at the root, others under /<locale>), with a header language switcher. You declare the locales in opts.locales, then drive the translation + per-locale builds with the clean-jsdoc CLI:

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

A build with no locales is unaffected. See Localize your docs for the full workflow (extract → translate → build), and the locales / defaultLocale reference.

Next steps