{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"packages-typedoc","path":"/packages/typedoc","type":"module","module":"packages-typedoc","title":"`@doc-kit/typedoc`","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A [TypeDoc](https://typedoc.org) plugin that writes the API reference of a\nTypeScript project, or of a JavaScript one documented with JSDoc, as\n[doc-kit Markdown](https://doc-kit.nodejs.org/specification). doc-kit then\nbuilds it into your site next to your hand-written pages: a page per module,\nnamespace and export, with signatures, typed lists, stability indicators and\nsource links.\n\n> \\[!IMPORTANT]\n> This plugin is experimental: its output and options may change in any\n> release.\n\nThis page is the plugin's reference.\n[Documenting TypeScript](https://doc-kit.nodejs.org/typescript) walks through\nit step by step, from a TypeScript or JavaScript project to a built site.","summary":"A TypeDoc plugin that writes the API reference of a TypeScript project, or of a JavaScript one documented with JSDoc, as doc-kit Markdown. doc-kit then builds it into your site next to your hand-written pages: a page per module, namespace and export, with signatures, typed lists, stability indicators and source links.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Install TypeDoc and the plugin, plus the doc-kit CLI and the website generators\nto build the site:\n\n```bash\nnpm install --save-dev typedoc@0.28 @doc-kit/typedoc @doc-kit/cli @doc-kit/generator-react\n```\n\nThe plugin is built for TypeDoc 0.28. Load it in your TypeDoc configuration,\nand set where the reference goes with `docKit`:\n\n```js displayName=\"typedoc.config.mjs\"\nimport { load } from '@doc-kit/typedoc';\n\nexport default {\n  plugin: [load],\n  entryPoints: ['src/index.ts'],\n  // Source links are relative to this: the root of your repository\n  basePath: '.',\n  docKit: 'docs/api',\n};\n```\n\nImport `load` rather than naming the plugin as a string: TypeDoc imports\nplugins named by a string from its own installation, where package managers\nsuch as pnpm hide your project's dependencies. `docKit` is the shortcut for\nthe plugin's `doc-kit` output, as `html` is for TypeDoc's own;\n`outputs: [{ name: 'doc-kit', path: 'docs/api' }]` works too.\n\nThen point doc-kit at the Markdown, and at its type map:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['html'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n    repository: 'your-org/your-repo',\n  },\n  metadata: { typeMap: 'docs/api/type-map.json' },\n};\n```\n\nGenerate the reference with TypeDoc, which finds `typedoc.config.mjs` on its\nown, then build the site:\n\n```bash\nnpx typedoc\nnpx doc-kit generate\n```","summary":"Install TypeDoc and the plugin, plus the doc-kit CLI and the website generators to build the site:","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev typedoc@0.28 @doc-kit/typedoc @doc-kit/cli @doc-kit/generator-react"},{"language":"js","displayName":"typedoc.config.mjs","code":"import { load } from '@doc-kit/typedoc';\n\nexport default {\n  plugin: [load],\n  entryPoints: ['src/index.ts'],\n  // Source links are relative to this: the root of your repository\n  basePath: '.',\n  docKit: 'docs/api',\n};"},{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['html'],\n  global: {\n    input: ['docs/**/*.md'],\n    output: 'out',\n    repository: 'your-org/your-repo',\n  },\n  metadata: { typeMap: 'docs/api/type-map.json' },\n};"},{"language":"bash","displayName":null,"code":"npx typedoc\nnpx doc-kit generate"}],"children":[]},{"kind":"section","id":"output","name":"Output","title":"Output","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The output directory follows TypeDoc's layout:\n\n| File                                          | What it holds                                                                                      |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `modules/plugins.md`                          | A page per module and namespace, listing its exports by group                                      |\n| `classes/Watcher.md`, `functions/build.md`, … | A page per exported class, interface, enum, type alias, function and variable                      |\n| `classes/plugins.BannerPlugin.md`             | An export of a namespace, or of a module when there are several entry points, prefixed by its name |\n| `interfaces/BuildOptions.input.md`            | A page per member of the types listed in [`docKitMemberPages`](#options)                           |\n| `type-map.json`                               | Type names mapped to their pages, for doc-kit's `metadata.typeMap`                                 |\n| `pages.json`                                  | Every page, for building your site's navigation                                                    |\n\n* With several entry points, each one is a module, so the pages of its exports\n  are prefixed by its name, the main entry point's included. An entry point\n  merged into the project with `@mergeModuleWith <project>` is the exception:\n  its exports become the project's own.\n* The project itself gets no page, so the reference's landing page is yours to\n  write (`docs/api/index.md`, for instance).\n* The plugin doesn't empty the directory before writing, so delete it before\n  regenerating when you remove or rename exports.\n* Pages link to each other with relative `.md` links, which doc-kit resolves.\n\nSource links point to `https://github.com/<repository>/blob/<ref>/<file>`.\nThe file path is relative to TypeDoc's `displayBasePath` or `basePath` (or,\nwithout either, the common directory of your sources), so set `basePath` to\nyour repository's root and doc-kit's\n[`global.repository`](https://doc-kit.nodejs.org/configuration#global-options)\nto the repository. On the website, `<ref>` is\n[`jsx-ast.ref`](https://doc-kit.nodejs.org/generators/jsx-ast#configuring),\n`'main'` by default. External declarations (TypeDoc's `externalPattern`) get\nno source link.","summary":"The output directory follows TypeDoc's layout:","examples":[],"children":[{"kind":"section","id":"the-type-map","name":"The type map","title":"The type map","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`type-map.json` maps each class, interface, enum and type alias to its page,\nfor doc-kit to\n[link the `{Type}` annotations](https://doc-kit.nodejs.org/generators/metadata#type-links)\nof the reference, and of any other page that names your types. Its paths\nstart with [`docKitBasePath`](#options) and have no extension, so the type\nlinks need a host that serves `/api/classes/Watcher` from `Watcher.html` (see\n[Page URLs](https://doc-kit.nodejs.org/publishing#page-urls)).","summary":"`type-map.json` maps each class, interface, enum and type alias to its page, for doc-kit to link the `{Type}` annotations of the reference, and of any other page that names your types. Its paths start with `docKitBasePath` and have no extension, so the type links need a host that serves `/api/classes/Watcher` from `Watcher.html` (see Page URLs).","examples":[],"children":[]},{"kind":"section","id":"the-page-list","name":"The page list","title":"The page list","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`pages.json` lists every page with its `name` (the full name, such as\n`plugins.BannerPlugin`), `kind` (`Class`, `Function`, …), `url` (the page path\ndoc-kit gives it, such as `/api/classes/Watcher`) and, when you use\n`@category`, its `category`. Types documented on a member's page (see\n[`docKitMemberPages`](#options)) are left out.\n\nThe `url` is the form the\n[website's sidebar](https://doc-kit.nodejs.org/generators/html#sidebar) links\ntake.\n[Building the sidebar](https://doc-kit.nodejs.org/typescript#building-the-sidebar)\nturns the list into sidebar groups.","summary":"`pages.json` lists every page with its `name` (the full name, such as `plugins.BannerPlugin`), `kind` (`Class`, `Function`, …), `url` (the page path doc-kit gives it, such as `/api/classes/Watcher`) and, when you use `@category`, its `category`. Types documented on a member's page (see `docKitMemberPages`) are left out.","examples":[],"children":[]}]},{"kind":"section","id":"how-code-and-comments-are-rendered","name":"How code and comments are rendered","title":"How code and comments are rendered","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"","summary":"","examples":[],"children":[{"kind":"section","id":"declarations","name":"Declarations","title":"Declarations","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* **Functions**, methods, and variables or type aliases of a function type\n  become doc-kit signatures: a heading such as `watcher.close([force])`, with\n  optional parameters in brackets, and a typed list of the parameters and the\n  return value. Each overload gets an entry of its own.\n  * Properties of object parameters are nested in the typed list. Only the\n    first paragraph of a parameter's description goes in the list; the rest\n    follows it.\n  * A `this` parameter becomes a `**Context:**` note. A `void` or `undefined`\n    return gets no `Returns:` item unless `@returns` describes it.\n* **Classes** get a `Class:` heading, constructors a `new Watcher()` one, and\n  static methods a `Static method:` one.\n* **Members** are documented on their type. Static and enum members use its\n  name (`Watcher.create()`, `Level.Info`), and instance members its name with\n  the first letter lowercased (`watcher.close()`) or the name set in\n  [`docKitReceivers`](#options). Each member is also anchored by its name alone\n  (`#resolveid` for `resolveId`), so links to it survive changes to its\n  signature. Members grouped with `@group` get a section per group.\n* **Properties** and accessors become entries with a `Type:` item. The\n  properties of object types, `Partial`, `Readonly` and `Required` ones\n  included, get entries nested under them.\n* **Events**: a class extending `EventEmitter<Events>`, or a type whose `on()`\n  takes a `(...args: Events[E]) => void` listener, gets an `Event:` entry per\n  property of `Events`. Each property is a tuple of the listener's arguments;\n  name its elements (`[error: Error, file: string]`), since unnamed ones are\n  left out.\n* **Inheritance**: classes and interfaces list what they extend in an\n  `Extends:` item, and the types extending them in an `Extended by` note.\n* **Types**: type parameters show their constraint (`keyof Events` for\n  `E extends keyof Events`), and the parts of a type past TypeDoc's\n  `maxTypeConversionDepth` show as `unknown`.\n* **Several entry points**: the pages of exports the main entry point doesn't\n  export say which entry points do, by module name (set with `@module`). The\n  main entry point is the one merged with `@mergeModuleWith <project>`, or\n  else the module TypeDoc lists first: the first by name with its default\n  `sort`, or the first entry point when `sortEntryPoints` is `false`.","summary":"","examples":[],"children":[]},{"kind":"section","id":"tags","name":"Tags","title":"Tags","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"* `@param` and `@returns` describe the items of the typed list.\n* `@deprecated` becomes a stability indicator of `0 - Deprecated`, followed by\n  the tag's text, and `@experimental` one of `1 - Experimental`.\n* `@default` and `@defaultValue` add a default to the `Type:` or parameter\n  item when they hold a value (a word, a sentence, or a one-line code block).\n  A longer default gets a \"Default\" section. Parameters without the tag show\n  their declared default.\n* `@example` follows the description, in an \"Example\" section.\n* `@see` follows the description as a \"See\" line, and `@throws` as a\n  `**Throws:**` one.\n* `{@link}` and `{@linkcode}` link to the target's page or entry.\n* The first sentence of `@summary`, or else of the first paragraph, describes\n  an export on its module's page, and a member in the lists linking to its own\n  page.\n* `@category` sets the page's `category` in the page list.\n* Block tags of your own, declared with TypeDoc's `blockTags` option, become\n  `**Tag:** content`. TypeDoc's other block tags, such as `@remarks` and\n  `@since`, are left out.","summary":"","examples":[],"children":[]}]},{"kind":"section","id":"options","name":"Options","title":"Options","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The plugin adds these options to TypeDoc's:\n\n* `docKit` {string} Where to write the reference, such as `'docs/api'`.\n  Setting it runs the `doc-kit` output.\n* `docKitBasePath` {string} Where the output directory sits under the directory\n  doc-kit's `input` glob starts from (`docs` for `docs/**/*.md`). The paths in\n  the type map and the page list start with it, and its leading and trailing\n  slashes are ignored. **Default:** the output directory's name (`'api'` for\n  `docs/api`).\n* `docKitTypeMap` {string | null} The type map's file name, in the output\n  directory. `null` or `''` leaves it out. **Default:** `'type-map.json'`.\n* `docKitPageList` {string | null} The page list's file name, in the output\n  directory. `null` or `''` leaves it out. **Default:** `'pages.json'`.\n* `docKitMemberPages` {string[]} Exported interfaces and classes whose members\n  each get a page of their own, such as a bundler's options. Wherever such a\n  type's members would be documented in full, each is listed instead, with its\n  type, the first sentence of its description and a link to its page. A type\n  that only one of these members uses (`TreeshakeOptions` in\n  `boolean | TreeshakeOptions`) is documented on that member's page, and links\n  to the type lead there. Names that match no exported interface or class with\n  members log a warning. **Default:** `[]`.\n* `docKitUrlAdapter` {Function} Adapts the URL of each page. It's called with\n  the page's default URL, without an extension (`'interfaces/Plugin'`), and its\n  TypeDoc reflection, and returns the URL to use (`'Interface.Plugin'`). Links,\n  the type map and the page list follow it. Set it in a JavaScript\n  configuration file. **Default:** `undefined`.\n* `docKitReceivers` {Record<string, string>} The name the members of a type are\n  documented on, by type name: `{ PluginContext: 'this' }` documents\n  `this.resolve()` rather than `pluginContext.resolve()`. **Default:** `{}`, so\n  members are documented on the type's name with its first letter lowercased.\n\nFor example, to keep the URLs of a site whose interface pages were at\n`Interface.<name>`:\n\n```js displayName=\"typedoc.config.mjs\"\nimport { load } from '@doc-kit/typedoc';\n\nexport default {\n  plugin: [load],\n  entryPoints: ['src/index.ts'],\n  docKit: 'docs/api',\n  docKitUrlAdapter: url => url.replace(/^interfaces\\//, 'Interface.'),\n};\n```","summary":"The plugin adds these options to TypeDoc's:","examples":[{"language":"js","displayName":"typedoc.config.mjs","code":"import { load } from '@doc-kit/typedoc';\n\nexport default {\n  plugin: [load],\n  entryPoints: ['src/index.ts'],\n  docKit: 'docs/api',\n  docKitUrlAdapter: url => url.replace(/^interfaces\\//, 'Interface.'),\n};"}],"children":[]}]}