theme jsdoc getting started

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.

Note

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

Install JSDoc and the theme as dev dependencies:

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

pnpm add -D jsdoc clean-jsdoc-theme

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

{
  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",
  },
}

Warning

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.

Run JSDoc against the config:

npx jsdoc -c jsdoc.json

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

npx serve dist

Tip

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.

Option	What it does
siteName	Header title — plain text, or a light/dark logo set with alt fallback text.
fonts	Override heading / body (Google Fonts, loaded for you) and mono.
colors / darkColors	Recolor the light / dark palettes — override just bg, accent, …, keep the rest.
sectionOrder	Order the top-level sidebar sections.
clubSidebarItems	Collapse related entries under a shared, collapsible parent.
menu	Custom links pinned above the sidebar, each with a lucide: / simpleicons: icon.
tutorials / docs	Render hand-written Markdown guides beside the generated reference.
copyPage	The per-page "copy page" / "open in LLM" button (on by default).

Note

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:

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

• Build an API reference — what becomes a page, the source-file viewer, and Source: file:line links.
• Build a guides site and Combine guides + API — add hand-written Markdown to the same site.
• Structure your sidebar — @category, @order, and the sidebar options.
• Authoring — callouts, steps, tabs, and embeds you can use in comments and prose.
• Localize your docs — ship the site in multiple languages.
• Prefer TypeScript? See TypeDoc Getting Started — same output, different toolchain.