clean-jsdoc-theme

A fast, modern, LLM-friendly documentation theme for JSDoc and TypeDoc. Point it at your source comments — and, optionally, a folder of Markdown guides — and v5 produces a static site: SSR-rendered chrome, lazy-hydrated Preact islands (sidebar, TOC, fuzzy command palette, theme toggle, settings, mobile nav, language switcher, copy-page button, code-block copy, tabbed code blocks, a Monaco source viewer), a co-located .md per page for LLMs, a built-in fuzzy search index (plus an optional Pagefind full-text index), and optional multi-language (i18n) builds — all framework-free, with no CSS or build config required to get started.

If clean-jsdoc-theme saves you time, please consider sponsoring its development — it directly funds the v5 rewrite and ongoing maintenance.

---

Architecture

Four boundary packages (utils → setu/rang → dwar), each independently testable, glued together by thin JSDoc and TypeDoc bridges, plus the i18n pair (aadesh + bhasha):

Package	What it does
@clean-jsdoc-theme/utils	Shared type contracts (SiteManifest, Page, RenderOptions, IslandName, …) and slug rules used by both setu and dwar.
@clean-jsdoc-theme/setu	JSDoc → SiteManifest. Walks the salty doclet collection into one MDX page per documented symbol (classes, interfaces, mixins, modules, namespaces, typedefs, globals) plus README/tutorials/source pages, and resolves {@link}/@see cross-references. No HTML, no JSX, no I/O.
@clean-jsdoc-theme/rang	Preact component library: chrome (Layout, Header, Footer, Brand), the hydratable islands (IslandName set), shadcn-style primitives (Button, ButtonGroup, Dialog, DropdownMenu), MDX element map, ISLAND_REGISTRY.
@clean-jsdoc-theme/dwar	Pure SiteManifest → HTML/CSS/JS renderer. Server-renders pages, bundles each island as its own ESM chunk via esbuild, emits CSS, exposes a separate Pagefind post-write step.
clean-jsdoc-theme	The JSDoc theme entry. A thin publish.ts bridge that wires the packages together and is what jsdoc -t clean-jsdoc-theme actually invokes.
@clean-jsdoc-theme/typedoc	The TypeDoc bridge — a plugin that feeds TypeDoc's reflections through the same setu → dwar pipeline, so a TypeScript project gets identical output. Selected via the outputs option in typedoc.json.
@clean-jsdoc-theme/aadesh	The clean-jsdoc CLI for the theme. Localization authoring lives under the i18n group (clean-jsdoc i18n extract/prompt/validate); build is top-level (one static site per locale). Reads locales from your existing jsdoc.json opts; the top-level namespace is reserved for future groups.
@clean-jsdoc-theme/bhasha	The pure, browser-safe i18n core: the UI string catalog, the t translator + LanguageProvider, and the API-slot key/hash scheme that setu, aadesh, and rang all share.

---

Quickstart

Both toolchains render through the same pipeline, so the output is identical — pick the entry point that matches your source. Serve over HTTP (Pagefind's full-text index needs HTTP to load).

JSDoc

pnpm add -D clean-jsdoc-theme jsdoc

Minimal jsdoc.json:

{
  "source": { "include": ["./src", "./README.md"] },
  "plugins": ["plugins/markdown"],
  "opts": {
    "encoding": "utf8",
    "destination": "dist",
    "recurse": true,
    "template": "./node_modules/clean-jsdoc-theme/dist"
  }
}

jsdoc -c jsdoc.json
pnpm dlx serve dist

TypeDoc

pnpm add -D typedoc @clean-jsdoc-theme/typedoc

Minimal typedoc.json — load the plugin, select its output, and put theme options under cleanJsdocTheme (TypeDoc's counterpart to JSDoc's opts):

{
  "entryPoints": ["src/index.ts"],
  "plugin": ["@clean-jsdoc-theme/typedoc"],
  "outputs": [{ "name": "clean-jsdoc-theme", "path": "dist" }],
  "cleanJsdocTheme": { "siteName": "My Library" }
}

typedoc
pnpm dlx serve dist

Runnable fixtures — pnpm install && pnpm run docs in each: examples/basic/ (JSDoc, covering every documentable kind, source-file viewers, tutorials, a README home page, per-island ESM chunks, and a Pagefind index), examples/typedoc-basic/ (TypeDoc), and examples/with-i18n-example/ (a 3-locale build).

Documentation

• Guides & full reference — ankdev.me/clean-jsdoc-theme: installation (JSDoc + TypeDoc), configuration, authoring, and theming.
• Live demo — ankdev.me/clean-jsdoc-theme/api-docs: a real generated API reference, so you can see the output before installing.
• FAQ & recipes — ankdev.me/clean-jsdoc-theme/guides/faq: embedding CodePen / YouTube, rich doc comments (callouts, steps, tabs), and common config tweaks.
• LLM skill — a downloadable skill (in SKILLS/) that turns any coding assistant into a setup expert.

---

Development

pnpm install
pnpm build         # build all packages
pnpm test          # vitest across every package
pnpm typecheck
pnpm lint
pnpm check:docs    # doc-consistency guard (package table, repo layout, island docs)

To iterate on the example end-to-end:

cd examples/basic
pnpm run docs      # build:theme (turbo) → jsdoc -c jsdoc.json → dist/
pnpm dlx serve dist

---

History

clean-jsdoc-theme has been in active development since its first commit on 10 November 2019.

---

License

MIT.