v4 → v5 への移行

v5 は土台から書き直されました: すべての page を server-render し、各 page に対して companion の .md を emit し、built-in の search と source viewer を ship し、 opts.docs の prose pipeline を追加します。configuration の表面はかなり変わりまし た — ですが移行は機械的で、この page（と下記の migration skill）が手順を案内します。

この作業はまるごと AI assistant に任せられます。 専用の migration skill があります — agent をこれに向ければ、 あなたの options を持ち上げ、引き継がれるものを rename し、なくなったものを削除し、 build を verify します。下の エージェントに任せる を 参照してください。

知っておくべき唯一のこと

v4 は theme options を opts.theme_opts.* の下に nest していました。v5 はそれ らを opts.* から直接 読み取ります — v5 に theme_opts block はありません。 つまり移行とは、要するに次のことです: options を theme_opts から外へ持ち上げ、 引き継がれる少数を rename し、残りを削除し、そして必要に応じて v5 の新機能を 取り入れる。

// v4 — opts.theme_opts の下に nest
{ opts: { template: "node_modules/clean-jsdoc-theme",
          theme_opts: { default_theme: "dark", title: "My Library" } } }

// v5 — opts の直下（theme_opts なし）
{ opts: { template: "node_modules/clean-jsdoc-theme",
          siteName: "My Library" } }

手順

1. 1
   Check compatibility

   v5 には JSDoc ≥ 4 と Node ≥ 20 が必要です。plugins/markdown plugin は theme にとってもう必須ではありません（v5 は Markdown を自前で render します）が、 残しておいても無害です。当面は v4 にとどまりたいですか? "clean-jsdoc-theme": "^4" で pin してください — v5 prereleases は npm の next tag の下に publish されるため、 ^4 はそれらを引き込みません。

2. 2
   Upgrade the package

   CODE

   コピー

   npm i -D clean-jsdoc-theme@latest   # または v5 prerelease 中は @next

3. 3
   Lift and rename options

   すべての key を theme_opts から外へ出して opts まで持ち上げ、 mapping table を適用し、それから空の theme_opts block を削除 します。引き継がれる options は次のとおりです（それ以外はすべて削除されます）:

   • base_url → basePath
   • title → siteName
   • sections → sectionOrder
   • create_style → customCss、include_css / add_style_path → customCssFile
   • add_scripts → customJs、include_js / add_script_path → customJsFile
   • menu → menu（再構成 — 下記参照）
4. 4
   Build and verify

   CODE

   コピー

   npx jsdoc -c jsdoc.json
   npx serve <destination>   # Pagefind の full-text search には HTTP が必要

   v5 は、残っている theme_opts key や v4 の option 名に対して 警告 を出し （「もしかして?」のヒント付き）、build を続行します — 出力を読み、指摘されたものを 修正してください。移行中はそれらの警告を厳格な errors に変えるために strict: true を設定し、終わったら緩めてください。

Option mapping

opts.theme_opts.<v4> → opts.<v5>。

menu が再構成されました: v4 の entry { title, link, target, class, id } は v5 の { id?, title?, link (or href)?, icon?, target?, class? } になります — icon（lucide:<name> / simpleicons:<name>）を追加できます。v5 では、 id は built-ins も選択し（{ id: "home" }、{ id: "source" }）、menu は sectionOrder より優先されます。menu と Structure your sidebar を参照してください。

移行前 / 移行後

{
  plugins: ["plugins/markdown"],
  opts: {
    template: "./node_modules/clean-jsdoc-theme",
    theme_opts: {
      default_theme: "dark",
      base_url: "https://example.com/docs/",
      title: "My Library",
      menu: [{ title: "GitHub", link: "https://github.com/me/lib", target: "_blank" }],
      sections: ["Classes", "Modules", "Global"],
      search: true,
      footer: "© My Library",
      include_css: ["./static/custom.css"],
    },
  },
}

{
  opts: {
    template: "./node_modules/clean-jsdoc-theme",
    basePath: "https://example.com/docs/",
    siteName: "My Library",
    menu: [
      { id: "home", title: "Home" },
      { title: "GitHub", link: "https://github.com/me/lib", icon: "simpleicons:github" },
    ],
    sectionOrder: ["Classes", "Modules", "Global"],
    footer: "© My Library",
    customCssFile: "./static/custom.css",
    // 削除: default_theme (auto), search (常時 on)
    docs: "./docs", // 省略可能な v5 の利点
  },
}

v5 で解放されるもの

移行は upgrade でもあります。v5 に移ったら、次に手を伸ばしてください:

• API のそばに Prose guides — docs + docGroups、このサイトが使っているのと同じ pipeline。
• Authoring primitives — comments と prose の中の callouts、steps、tabs、live embeds。
• Sidebar structure — @category / @order tags、clubSidebarItems、menu。
• LLM features — page ごとの companion .md、copy-page ボタン、aiPrompt。

エージェントに任せる

手作業でやりたくないですか? AI assistant を migration skill に向けてください。 これは焦点を絞った、source-verified な手順で、あなたの v4 config を検出し、上記の mapping を適用し、menu を再構成し、なくなったものを削除し、build を verify します — それから umbrella skill を渡し、assistant が新しい v5 features の採用を手伝える ようにします。

• Migration skill: SKILLS/migrate-v4-to-v5/SKILL.md — umbrella skill と同じ方法で download してください:

  CODE

  コピー

  curl -O https://raw.githubusercontent.com/ankitskvmdam/clean-jsdoc-theme/master/SKILLS/migrate-v4-to-v5/SKILL.md

  それを assistant に添付し（または .claude/skills/ に置き）、 "migrate my project from clean-jsdoc-theme v4 to v5." と伝えてください。

• Canonical reference: 網羅的な MIGRATION.md と machine-readable な migration-map.json が skill を支えています — codemods に役立ちます。

関連項目

• Use with an LLM — umbrella skill と、それを assistant に 渡す方法。
• Configuration — すべての v5 option を詳細に。
• JSDoc Getting Started — ゼロからの新しい v5 setup。