clean-jsdoc-theme

Getting Started

This guide walks through adding clean-jsdoc-theme to a JSDoc project and configuring the most useful options.

🚧 Work in progress. The full configuration reference is still being written. The options below are the ones you will reach for most often.

Install

Install the theme alongside JSDoc as dev dependencies:

npm install --save-dev jsdoc clean-jsdoc-theme
# or with pnpm
pnpm add -D jsdoc clean-jsdoc-theme

Configure JSDoc

Point JSDoc at the theme with a jsdoc.json in your project root:

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

Then build your docs:

npx jsdoc -c jsdoc.json

The site is written to dist/. Open dist/index.html in a browser, or serve the folder during development:

npx serve dist

Common options

All theme options live under opts in jsdoc.json.

OptionWhat it does
siteNameSite title shown in the header. Plain text, or a logo set ({ default, dark, light, alt }).
readmeMarkdown file rendered as the site home page.
docsA directory of Markdown/HTML guides rendered as prose pages (see below).
docGroupsOrder of the top-level doc groups in the sidebar.
sectionOrderOrder of all top-level sidebar sections (doc groups and API kinds).
menuExtra links shown above the sidebar nav (with optional icons).
fontsOverride heading / body (Google Fonts) and mono (CSS stack).
copyPageToggle / configure the "copy page" + open-in-LLM button.
clubSidebarItemsGroup related sidebar entries under a shared parent.
customCss / customJsInline CSS/JS injected into every page. (customCssFile / customJsFile for files.)

Adding prose pages

Set opts.docs to a directory and every *.md / *.html file in it becomes a page. The filesystem layout drives the URL and the sidebar group:

{
  "opts": {
    "docs": "./docs",
    "docGroups": ["Getting Started", "Guides"],
    "defaultDocGroup": "Docs"
  }
}

Per-file YAML frontmatter (title, group, order, slug, hidden) overrides the directory-derived defaults. A root docs/index.md becomes the home page.

Adding a sidebar menu

{
  "opts": {
    "menu": [
      { "title": "Home", "link": "/", "icon": "lucide:home" },
      {
        "title": "GitHub",
        "link": "https://github.com/ankitskvmdam/clean-jsdoc-theme",
        "icon": "simpleicons:github"
      }
    ]
  }
}

Icons use the lucide: or simpleicons: prefix and are loaded from a CDN.