@kubb/plugin-redoc 5.0.0-beta.4 → 5.0.0-beta.42

package/README.md

@@ -1,19 +1,16 @@
 <div align="center">
-  <h1>Plugin Redoc</h1>
   <a href="https://kubb.dev" target="_blank" rel="noopener noreferrer">
-    <img width="180" src="https://raw.githubusercontent.com/kubb-labs/kubb/main/assets/logo.png" alt="Kubb logo">
+    <img src="https://kubb.dev/og.png" alt="Kubb banner">
   </a>
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![Coverage][coverage-src]][coverage-href]
+[![Stars][stars-src]][stars-href]
 [![License][license-src]][license-href]
-[![Sponsors][sponsors-src]][sponsors-href]
+[![Node][node-src]][node-href]
 
 <h4>
-<a href="https://codesandbox.io/s/github/kubb-labs/kubb/tree/main//examples/typescript" target="_blank">View Demo</a>
-<span> · </span>
-<a href="https://kubb.dev/" target="_blank">Documentation</a>
+<a href="https://kubb.dev/plugins/redoc" target="_blank">Documentation</a>
 <span> · </span>
 <a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Report Bug</a>
 <span> · </span>
@@ -21,11 +18,31 @@
 </h4>
 </div>
 
-Create beautiful docs with Redoc.
+<br />
+
+# @kubb/plugin-redoc
+
+### Generate a ReDoc API reference from OpenAPI
+
+`@kubb/plugin-redoc` generates a ReDoc API reference page from your OpenAPI specification. The output is a standalone HTML file you can host without a build step or server.
+
+## Installation
+
+```bash
+bun add @kubb/plugin-redoc
+# or
+pnpm add @kubb/plugin-redoc
+# or
+npm install @kubb/plugin-redoc
+```
+
+## Documentation
+
+See the [full documentation](https://kubb.dev/plugins/redoc) for configuration options and examples.
 
 ## Supporting Kubb
 
-Kubb uses an MIT-licensed open source project with its ongoing development made possible entirely by the support of Sponsors. If you would like to become a sponsor, please consider:
+Kubb is an open source project, and its development is funded entirely by sponsors. If you would like to become a sponsor, please consider:
 
 - [Become a Sponsor on GitHub](https://github.com/sponsors/stijnvanhulle)
 
@@ -35,19 +52,19 @@ Kubb uses an MIT-licensed open source project with its ongoing development made
   </a>
 </p>
 
+## License
+
+[MIT](https://github.com/kubb-labs/plugins/blob/main/LICENSE)
+
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/@kubb/plugin-redoc?flat&colorA=18181B&colorB=f58517
-[npm-version-href]: https://npmjs.com/package/@kubb/plugin-redoc
-[npm-downloads-src]: https://img.shields.io/npm/dm/@kubb/plugin-redoc?flat&colorA=18181B&colorB=f58517
-[npm-downloads-href]: https://npmjs.com/package/@kubb/plugin-redoc
-[license-src]: https://img.shields.io/github/license/kubb-labs/kubb.svg?flat&colorA=18181B&colorB=f58517
+[npm-version-src]: https://shieldcn.dev/npm/v/@kubb/plugin-redoc.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[npm-version-href]: https://npmx.dev/package/@kubb/plugin-redoc
+[npm-downloads-src]: https://shieldcn.dev/npm/dm/@kubb/plugin-redoc.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[npm-downloads-href]: https://npmx.dev/package/@kubb/plugin-redoc
+[stars-src]: https://shieldcn.dev/github/stars/kubb-labs/kubb.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[stars-href]: https://github.com/kubb-labs/kubb
+[license-src]: https://shieldcn.dev/npm/license/@kubb/plugin-redoc.svg?variant=secondary&size=xs&theme=zinc
 [license-href]: https://github.com/kubb-labs/kubb/blob/main/LICENSE
-[build-src]: https://img.shields.io/github/actions/workflow/status/kubb-labs/kubb/ci.yaml?style=flat&colorA=18181B&colorB=f58517
-[build-href]: https://www.npmjs.com/package/@kubb/plugin-redoc
-[minified-src]: https://img.shields.io/bundlephobia/min/@kubb/plugin-redoc?style=flat&colorA=18181B&colorB=f58517
-[minified-href]: https://www.npmjs.com/package/@kubb/plugin-redoc
-[coverage-src]: https://img.shields.io/codecov/c/github/kubb-labs/kubb?style=flat&colorA=18181B&colorB=f58517
-[coverage-href]: https://www.npmjs.com/package/@kubb/plugin-redoc
-[sponsors-src]: https://img.shields.io/github/sponsors/stijnvanhulle?style=flat&colorA=18181B&colorB=f58517
-[sponsors-href]: https://github.com/sponsors/stijnvanhulle/
+[node-src]: https://shieldcn.dev/npm/node/@kubb/plugin-redoc.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[node-href]: https://npmx.dev/package/@kubb/plugin-redoc

package/dist/index.cjs

@@ -31,7 +31,6 @@ let _kubb_adapter_oas = require("@kubb/adapter-oas");
 let _kubb_core = require("@kubb/core");
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
-let node_url = require("node:url");
 let handlebars = require("handlebars");
 handlebars = __toESM(handlebars);
 //#region ../../internals/utils/src/string.ts
@@ -52,13 +51,16 @@ function trimExtName(text) {
 }
 //#endregion
 //#region package.json
-var version = "5.0.0-beta.4";
+var version = "5.0.0-beta.42";
 //#endregion
 //#region src/redoc.tsx
-const __filename$1 = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
-const __dirname$1 = node_path.default.dirname(__filename$1);
+/**
+* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
+* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
+* the generated file works without further build steps.
+*/
 async function getPageHTML(api, { title, disableGoogleFont, templateOptions } = {}) {
-	const templateFileName = node_path.default.join(__dirname$1, "../static/redoc.hbs");
+	const templateFileName = node_path.default.join(__dirname, "../static/redoc.hbs");
 	return handlebars.default.compile(node_fs.default.readFileSync(templateFileName).toString())({
 		title: title || api.info.title || "ReDoc documentation",
 		redocHTML: `
@@ -77,7 +79,30 @@ async function getPageHTML(api, { title, disableGoogleFont, templateOptions } =
 }
 //#endregion
 //#region src/plugin.ts
+/**
+* Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+* cross-plugin dependency references.
+*/
 const pluginRedocName = "plugin-redoc";
+/**
+* Generates a self-contained static HTML documentation page from your OpenAPI
+* spec using Redoc. The file is regenerated on every Kubb build, so the docs
+* stay in lockstep with the spec the rest of your code is generated from.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { pluginRedoc } from '@kubb/plugin-redoc'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginRedoc({ output: { path: 'docs.html' } }),
+*   ],
+* })
+* ```
+*/
 const pluginRedoc = (0, _kubb_core.definePlugin)((options) => {
 	const { output = { path: "docs.html" } } = options;
 	return {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["__filename","__dirname","path","pkg","fs","adapterOasName","path","ast"],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = path.dirname(__filename)\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(__dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,IAAI;AACtC,KAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,SAAS,CAC/C,QAAO,KAAK,MAAM,GAAG,SAAS;AAEhC,QAAO;;;;;;;AE5DT,MAAMA,gBAAAA,GAAAA,SAAAA,eAAAA,QAAAA,MAAAA,CAAAA,cAAAA,WAAAA,CAAAA,KAA2C;AACjD,MAAMC,cAAYC,UAAAA,QAAK,QAAQF,aAAW;AAQ1C,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,EAAE,EAAE;CACnI,MAAM,mBAAmBE,UAAAA,QAAK,KAAKD,aAAW,sBAAsB;AAEpE,QADiBE,WAAAA,QAAI,QAAQC,QAAAA,QAAG,aAAa,iBAAiB,CAAC,UAAU,CAC1D,CAAC;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC;;;;;;EAM3C;EACA;EACD,CAAC;;;;ACtBJ,MAAa,kBAAkB;AAE/B,MAAa,eAAA,GAAA,WAAA,eAAyC,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,KAAK;AAE3C,QAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;AAC7B,OAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,KAAK;IAC9B,SAAS,EAAE;IACX,UAAU,EAAE;IACb,CAAC;GAEF,MAAM,UAAU,IAAI,OAAO;AAE3B,OAAI,SAAS,SAASC,kBAAAA,eACpB,OAAM,IAAI,MACR,IAAI,gBAAgB,uIACrB;GAGH,MAAM,WAAY,QAAgC;AAElD,OAAI,CAAC,SACH,OAAM,IAAI,MACR,IAAI,gBAAgB,yHACrB;GAGH,MAAM,OAAOC,YAAAA,QAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK;GAClE,MAAM,WAAW,MAAM,YAAY,SAAS;AAE5C,OAAI,WAAW;IACb,UAAU;IACV,MAAMA,YAAAA,QAAK,QAAQ,MAAM,OAAO,QAAQ,cAAc;IACtD,SAAS,CACPC,WAAAA,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAACA,WAAAA,IAAI,WAAW,SAAS,CAAC;KAClC,CAAC,CACH;IACF,CAAC;KAEL;EACF;EACD"}
+{"version":3,"file":"index.cjs","names":["path","pkg","fs","adapterOasName","path","ast"],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\n/**\n * Renders a self-contained Redoc HTML page for an OpenAPI document. The page\n * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so\n * the generated file works without further build steps.\n */\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(import.meta.dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and\n * cross-plugin dependency references.\n */\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\n/**\n * Generates a self-contained static HTML documentation page from your OpenAPI\n * spec using Redoc. The file is regenerated on every Kubb build, so the docs\n * stay in lockstep with the spec the rest of your code is generated from.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { pluginRedoc } from '@kubb/plugin-redoc'\n *\n * export default defineConfig({\n *   input: { path: './petStore.yaml' },\n *   output: { path: './src/gen' },\n *   plugins: [\n *     pluginRedoc({ output: { path: 'docs.html' } }),\n *   ],\n * })\n * ```\n */\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,GAAG;CACrC,IAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,QAAQ,GAC9C,OAAO,KAAK,MAAM,GAAG,QAAQ;CAE/B,OAAO;AACT;;;;;;;;;;;AEnDA,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,CAAC,GAAG;CACnI,MAAM,mBAAmBA,UAAAA,QAAK,KAAA,WAA0B,qBAAqB;CAE7E,OADiBC,WAAAA,QAAI,QAAQC,QAAAA,QAAG,aAAa,gBAAgB,EAAE,SAAS,CAC1D,EAAE;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,CAAC,EAAE;;;;;;EAM3C;EACA;CACF,CAAC;AACH;;;;;;;ACpBA,MAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqB/B,MAAa,eAAA,GAAA,WAAA,eAAyC,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,MAAM;CAE3C,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,IAAI;IAC7B,SAAS,CAAC;IACV,UAAU,CAAC;GACb,CAAC;GAED,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAASC,kBAAAA,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,sIACtB;GAGF,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,wHACtB;GAGF,MAAM,OAAOC,YAAAA,QAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,IAAI;GACjE,MAAM,WAAW,MAAM,YAAY,QAAQ;GAE3C,IAAI,WAAW;IACb,UAAU;IACV,MAAMA,YAAAA,QAAK,QAAQ,MAAM,OAAO,QAAQ,aAAa;IACrD,SAAS,CACPC,WAAAA,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAACA,WAAAA,IAAI,WAAW,QAAQ,CAAC;IAClC,CAAC,CACH;GACF,CAAC;EACH,EACF;CACF;AACF,CAAC"}

package/dist/index.d.ts

@@ -1,12 +1,16 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import * as _$_kubb_core0 from "@kubb/core";
+import { t as __name } from "./chunk-C0LytTxp.js";
 import { Exclude, Include, Output, Override, PluginFactoryOptions } from "@kubb/core";
 
 //#region src/types.d.ts
 type Options = {
+  /**
+   * Output location of the generated Redoc HTML file. The path is resolved
+   * against the global `output.path` set on `defineConfig`.
+   */
   output?: {
     /**
-     * Output path for the generated HTML documentation.
+     * File path of the generated HTML, relative to the global `output.path`.
+     * Unlike most plugins, this points at a single file rather than a directory.
      *
      * @default 'docs.html'
      */
@@ -30,8 +34,31 @@ declare global {
 }
 //#endregion
 //#region src/plugin.d.ts
+/**
+ * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
 declare const pluginRedocName = "plugin-redoc";
-declare const pluginRedoc: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginRedoc>;
+/**
+ * Generates a self-contained static HTML documentation page from your OpenAPI
+ * spec using Redoc. The file is regenerated on every Kubb build, so the docs
+ * stay in lockstep with the spec the rest of your code is generated from.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginRedoc } from '@kubb/plugin-redoc'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginRedoc({ output: { path: 'docs.html' } }),
+ *   ],
+ * })
+ * ```
+ */
+declare const pluginRedoc: (options?: Options | undefined) => import("@kubb/core").Plugin<PluginRedoc>;
 //#endregion
 export { type PluginRedoc, pluginRedoc as default, pluginRedoc, pluginRedocName };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,9 +1,8 @@
-import "./chunk--u3MIqq1.js";
+import "./chunk-C0LytTxp.js";
 import path from "node:path";
 import { adapterOasName } from "@kubb/adapter-oas";
 import { ast, definePlugin } from "@kubb/core";
 import fs from "node:fs";
-import { fileURLToPath } from "node:url";
 import pkg from "handlebars";
 //#region ../../internals/utils/src/string.ts
 /**
@@ -23,13 +22,16 @@ function trimExtName(text) {
 }
 //#endregion
 //#region package.json
-var version = "5.0.0-beta.4";
+var version = "5.0.0-beta.42";
 //#endregion
 //#region src/redoc.tsx
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+/**
+* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
+* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
+* the generated file works without further build steps.
+*/
 async function getPageHTML(api, { title, disableGoogleFont, templateOptions } = {}) {
-	const templateFileName = path.join(__dirname, "../static/redoc.hbs");
+	const templateFileName = path.join(import.meta.dirname, "../static/redoc.hbs");
 	return pkg.compile(fs.readFileSync(templateFileName).toString())({
 		title: title || api.info.title || "ReDoc documentation",
 		redocHTML: `
@@ -48,7 +50,30 @@ async function getPageHTML(api, { title, disableGoogleFont, templateOptions } =
 }
 //#endregion
 //#region src/plugin.ts
+/**
+* Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+* cross-plugin dependency references.
+*/
 const pluginRedocName = "plugin-redoc";
+/**
+* Generates a self-contained static HTML documentation page from your OpenAPI
+* spec using Redoc. The file is regenerated on every Kubb build, so the docs
+* stay in lockstep with the spec the rest of your code is generated from.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { pluginRedoc } from '@kubb/plugin-redoc'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginRedoc({ output: { path: 'docs.html' } }),
+*   ],
+* })
+* ```
+*/
 const pluginRedoc = definePlugin((options) => {
 	const { output = { path: "docs.html" } } = options;
 	return {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = path.dirname(__filename)\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(__dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,IAAI;AACtC,KAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,SAAS,CAC/C,QAAO,KAAK,MAAM,GAAG,SAAS;AAEhC,QAAO;;;;;;;AE5DT,MAAM,aAAa,cAAc,OAAO,KAAK,IAAI;AACjD,MAAM,YAAY,KAAK,QAAQ,WAAW;AAQ1C,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,EAAE,EAAE;CACnI,MAAM,mBAAmB,KAAK,KAAK,WAAW,sBAAsB;AAEpE,QADiB,IAAI,QAAQ,GAAG,aAAa,iBAAiB,CAAC,UAAU,CAC1D,CAAC;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC;;;;;;EAM3C;EACA;EACD,CAAC;;;;ACtBJ,MAAa,kBAAkB;AAE/B,MAAa,cAAc,cAA2B,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,KAAK;AAE3C,QAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;AAC7B,OAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,KAAK;IAC9B,SAAS,EAAE;IACX,UAAU,EAAE;IACb,CAAC;GAEF,MAAM,UAAU,IAAI,OAAO;AAE3B,OAAI,SAAS,SAAS,eACpB,OAAM,IAAI,MACR,IAAI,gBAAgB,uIACrB;GAGH,MAAM,WAAY,QAAgC;AAElD,OAAI,CAAC,SACH,OAAM,IAAI,MACR,IAAI,gBAAgB,yHACrB;GAGH,MAAM,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK;GAClE,MAAM,WAAW,MAAM,YAAY,SAAS;AAE5C,OAAI,WAAW;IACb,UAAU;IACV,MAAM,KAAK,QAAQ,MAAM,OAAO,QAAQ,cAAc;IACtD,SAAS,CACP,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAAC,IAAI,WAAW,SAAS,CAAC;KAClC,CAAC,CACH;IACF,CAAC;KAEL;EACF;EACD"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\n/**\n * Renders a self-contained Redoc HTML page for an OpenAPI document. The page\n * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so\n * the generated file works without further build steps.\n */\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(import.meta.dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and\n * cross-plugin dependency references.\n */\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\n/**\n * Generates a self-contained static HTML documentation page from your OpenAPI\n * spec using Redoc. The file is regenerated on every Kubb build, so the docs\n * stay in lockstep with the spec the rest of your code is generated from.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { pluginRedoc } from '@kubb/plugin-redoc'\n *\n * export default defineConfig({\n *   input: { path: './petStore.yaml' },\n *   output: { path: './src/gen' },\n *   plugins: [\n *     pluginRedoc({ output: { path: 'docs.html' } }),\n *   ],\n * })\n * ```\n */\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,GAAG;CACrC,IAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,QAAQ,GAC9C,OAAO,KAAK,MAAM,GAAG,QAAQ;CAE/B,OAAO;AACT;;;;;;;;;;;AEnDA,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,CAAC,GAAG;CACnI,MAAM,mBAAmB,KAAK,KAAK,OAAO,KAAK,SAAS,qBAAqB;CAE7E,OADiB,IAAI,QAAQ,GAAG,aAAa,gBAAgB,EAAE,SAAS,CAC1D,EAAE;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,CAAC,EAAE;;;;;;EAM3C;EACA;CACF,CAAC;AACH;;;;;;;ACpBA,MAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqB/B,MAAa,cAAc,cAA2B,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,MAAM;CAE3C,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,IAAI;IAC7B,SAAS,CAAC;IACV,UAAU,CAAC;GACb,CAAC;GAED,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAAS,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,sIACtB;GAGF,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,wHACtB;GAGF,MAAM,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,IAAI;GACjE,MAAM,WAAW,MAAM,YAAY,QAAQ;GAE3C,IAAI,WAAW;IACb,UAAU;IACV,MAAM,KAAK,QAAQ,MAAM,OAAO,QAAQ,aAAa;IACrD,SAAS,CACP,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAAC,IAAI,WAAW,QAAQ,CAAC;IAClC,CAAC,CACH;GACF,CAAC;EACH,EACF;CACF;AACF,CAAC"}

package/extension.yaml

@@ -2,18 +2,18 @@ $schema: https://kubb.dev/schemas/extension.json
 kind: plugin
 id: plugin-redoc
 name: Redoc
-description: Generate API documentation with Redoc from OpenAPI specifications.
+description: Render your OpenAPI spec as a single-file HTML page using Redoc, regenerated as part of the Kubb build.
 category: documentation
 type: official
-npmPackage: "@kubb/plugin-redoc"
+npmPackage: '@kubb/plugin-redoc'
 docsPath: /plugins/plugin-redoc
 repo: https://github.com/kubb-labs/plugins
 maintainers:
   - name: Stijn Van Hulle
     github: stijnvanhulle
 compatibility:
-  kubb: ">=5.0.0"
-  node: ">=22"
+  kubb: '>=5.0.0'
+  node: '>=22'
 tags:
   - redoc
   - api-docs
@@ -32,25 +32,61 @@ featured: false
 icon:
   light: https://kubb.dev/feature/openapi.svg
 intro: |
-  Generate interactive API documentation from your OpenAPI schema using [Redoc](https://redocly.com/).
+  # @kubb/plugin-redoc
+
+  Generate a static HTML documentation page for your OpenAPI spec using [Redoc](https://redocly.com/). The page is self-contained — drop it on any static host or open it locally.
+
+  Because the file is regenerated on every Kubb build, your docs stay in lockstep with the spec your code was generated from.
 options:
   - name: output
-    type: "{ path: string }"
+    type: '{ path: string }'
     required: false
-    description: Specify the output path for the generated documentation HTML file.
+    default: "{ path: 'docs.html' }"
+    description: Output location of the generated HTML file.
     properties:
       - name: path
         type: string
         required: true
         description: |
-          The output file path for the generated documentation HTML.
+          File path of the generated HTML, relative to the global `output.path`.
+
+          Use a `.html` extension. Unlike most plugins, this option points at a single file rather than a directory.
         tip: |
-          if `output.path` is a file, `group` cannot be used.
+          When `output.path` points to a single file, the `group` option cannot be used because every operation ends up in the same file.
+        examples:
+          - name: kubb.config.ts
+            files:
+              - lang: typescript
+                twoslash: false
+                code: |
+                  import { defineConfig } from 'kubb'
+                  import { pluginTs } from '@kubb/plugin-ts'
+
+                  export default defineConfig({
+                    input: { path: './petStore.yaml' },
+                    output: { path: './src/gen' },
+                    plugins: [
+                      pluginTs({
+                        output: { path: './types' },
+                      }),
+                    ],
+                  })
+          - name: Resulting tree
+            files:
+              - lang: text
+                twoslash: false
+                code: |
+                  src/
+                  └── gen/
+                      └── types/
+                          ├── Pet.ts
+                          └── Store.ts
         default: "'docs.html'"
 examples:
   - name: kubb.config.ts
     files:
       - lang: typescript
+        twoslash: false
         code: |
           import { defineConfig } from 'kubb'
           import { pluginRedoc } from '@kubb/plugin-redoc'
@@ -64,4 +100,3 @@ examples:
               }),
             ],
           })
-        twoslash: false

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@kubb/plugin-redoc",
-  "version": "5.0.0-beta.4",
-  "description": "Redoc documentation generator plugin for Kubb, creating beautiful, interactive API documentation from OpenAPI specifications.",
+  "version": "5.0.0-beta.42",
+  "description": "Generate a beautiful, interactive ReDoc API reference page from your OpenAPI specification. Produces a standalone HTML file with a responsive, developer-friendly UI.",
   "keywords": [
     "api-docs",
-    "code-generator",
+    "api-reference",
+    "code-generation",
     "codegen",
     "documentation",
-    "interactive-docs",
     "kubb",
     "openapi",
-    "plugins",
     "redoc",
     "swagger",
     "typescript"
@@ -51,8 +50,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/adapter-oas": "5.0.0-beta.4",
-    "@kubb/core": "5.0.0-beta.4",
+    "@kubb/adapter-oas": "5.0.0-beta.42",
+    "@kubb/core": "5.0.0-beta.42",
     "handlebars": "^4.7.9"
   },
   "devDependencies": {
@@ -75,6 +74,7 @@
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/plugin.ts

@@ -8,8 +8,31 @@ import { version } from '../package.json'
 import { getPageHTML } from './redoc.tsx'
 import type { PluginRedoc } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
 export const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']
 
+/**
+ * Generates a self-contained static HTML documentation page from your OpenAPI
+ * spec using Redoc. The file is regenerated on every Kubb build, so the docs
+ * stay in lockstep with the spec the rest of your code is generated from.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginRedoc } from '@kubb/plugin-redoc'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginRedoc({ output: { path: 'docs.html' } }),
+ *   ],
+ * })
+ * ```
+ */
 export const pluginRedoc = definePlugin<PluginRedoc>((options) => {
   const { output = { path: 'docs.html' } } = options
 

package/src/redoc.tsx

@@ -1,20 +1,21 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import type { AdapterOas } from '@kubb/adapter-oas'
 import pkg from 'handlebars'
 
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
 type BuildDocsOptions = {
   title?: string
   disableGoogleFont?: boolean
   templateOptions?: any
 }
 
+/**
+ * Renders a self-contained Redoc HTML page for an OpenAPI document. The page
+ * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
+ * the generated file works without further build steps.
+ */
 export async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {
-  const templateFileName = path.join(__dirname, '../static/redoc.hbs')
+  const templateFileName = path.join(import.meta.dirname, '../static/redoc.hbs')
   const template = pkg.compile(fs.readFileSync(templateFileName).toString())
   return template({
     title: title || api.info.title || 'ReDoc documentation',

package/src/types.ts

@@ -1,9 +1,14 @@
 import type { Exclude, Include, Output, Override, PluginFactoryOptions } from '@kubb/core'
 
 export type Options = {
+  /**
+   * Output location of the generated Redoc HTML file. The path is resolved
+   * against the global `output.path` set on `defineConfig`.
+   */
   output?: {
     /**
-     * Output path for the generated HTML documentation.
+     * File path of the generated HTML, relative to the global `output.path`.
+     * Unlike most plugins, this points at a single file rather than a directory.
      *
      * @default 'docs.html'
      */