clean-jsdoc-theme

Use with an LLM

This theme is built for LLMs — every page ships a companion .md and a "copy / open in Claude · ChatGPT · Perplexity" button. This page is the other half of that story: a single, downloadable skill file that teaches any assistant how to use and extend clean-jsdoc-theme itself.

It lives in the repo's SKILLS/ folder as SKILLS/clean-jsdoc-theme/SKILL.md. Hand it to your coding assistant and it stops guessing — it configures the theme, authors your guides, and structures your sidebar correctly the first time.

SKILLS/ is where focused skills will live as the project grows (per-package skills, "build a guides site", "build an API reference", …). Today it ships the umbrella clean-jsdoc-theme skill that covers everything below.

What it is

SKILL.md is a self-contained Markdown document that captures the whole theme in one place — verified against the source, not the model's memory. It's written in the agent-skill format (a name + description frontmatter block), so it drops straight into agents that support skills, but it's just Markdown: any LLM can read it.

It covers, end to end:

  • Setup — JSDoc and TypeDoc, with minimal working configs.
  • Every configuration option — the opts / cleanJsdocTheme reference, plus the JSDoc-only templates.default ones.
  • Authoring — callouts, steps, tabs, embeds, and the @category / @order / @iframe custom tags, with the exact syntax rules.
  • The docs directory & frontmatter — how files become pages.
  • The sidebar model — the one group/order engine and all its levers.
  • Cross-references and source links, the LLM features, and theming.
  • The package architecture (utils · setu · rang · dwar) for anyone extending the internals.
  • A gotchas & troubleshooting section for the mistakes assistants make most.

Why it matters

clean-jsdoc-theme isn't the default JSDoc template, and an assistant working from generic "JSDoc theme" knowledge will get the details wrong — it'll forget that plugins/markdown is required, miss that custom tags need allowUnknownTags, or assume spaces nest a @category path when only / does.

Front-loading the skill turns a back-and-forth ("that option doesn't exist…", "try this instead…") into a correct first answer. It's the same idea as the companion .md the theme emits for your docs — give the model the source of truth up front and it reads your project as fluently as a person does.

How to use it

  1. 1
    Download it

    The skill is a folder — SKILLS/clean-jsdoc-theme/ — a lean SKILL.md plus on-demand reference/ files (the assistant reads only the slice it needs). Grab the whole folder:

    CODE
    npx degit ankitskvmdam/clean-jsdoc-theme/SKILLS/clean-jsdoc-theme clean-jsdoc-theme

    Or just open SKILL.md on GitHub and copy it — the SKILL.md is self-sufficient for most questions and links to the reference files for the rest.

  2. 2
    Give it to your assistant

    Pick whichever matches your setup:

    It's a ready-to-use skill. Drop the folder into your project (or user) skills directory so the agent loads it — and its reference/ files — on demand:

    CODE
    npx degit ankitskvmdam/clean-jsdoc-theme/SKILLS/clean-jsdoc-theme .claude/skills/clean-jsdoc-theme

    The name / description frontmatter is what lets the agent decide when to apply it; the SKILL.md then pulls in the matching reference/ file per task.

  3. 3
    Ask away

    Anything from "write the jsdoc.json for a guides-only site" to "why is my @category showing two groups?" now gets an answer grounded in how the theme actually works.

Keep it current

SKILL.md is versioned alongside the code (it carries a skill-revision stamp) and verified against the source, so a fresh copy always matches the theme you're on. The skill also teaches the assistant to check for updates — when relevant, and at most once per session, it compares its revision against the published copy and your installed theme version against npm's latest, and offers to update if either is behind. Re-download it after upgrading the theme to pick up new options and features.

See also