{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"typescript","path":"/typescript","type":"module","module":"typescript","title":"Documenting TypeScript","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"If your API is written in TypeScript, or in JavaScript with JSDoc comments,\nits reference can come from the source. [TypeDoc](https://typedoc.org) reads\nyour code and its doc comments, the `@doc-kit/typedoc` plugin writes them as\ndoc-kit Markdown (a page per export, with signatures, typed lists, stability\nand source links), and doc-kit builds those pages into one site with your\nhand-written guides.\n\n> \\[!NOTE]\n> `@doc-kit/typedoc` is experimental: its output and options can still change.\n\nIt takes two commands: `npx typedoc` writes the reference into `docs/api/`,\nthen `npx doc-kit generate` builds everything in `docs/`.","summary":"If your API is written in TypeScript, or in JavaScript with JSDoc comments, its reference can come from the source. TypeDoc reads your code and its doc comments, the `@doc-kit/typedoc` plugin writes them as doc-kit Markdown (a page per export, with signatures, typed lists, stability and source links), and doc-kit builds those pages into one site with your hand-written guides.","examples":[],"children":[{"kind":"section","id":"install","name":"Install","title":"Install","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpm install --save-dev typedoc@0.28 @doc-kit/typedoc @doc-kit/cli @doc-kit/generator-react\n```\n\n`typedoc` and `@doc-kit/typedoc` write the reference; the plugin is built for\nTypeDoc 0.28. `@doc-kit/cli` and `@doc-kit/generator-react` build the site, as\nin [Getting started](./getting-started.html).","summary":"`typedoc` and `@doc-kit/typedoc` write the reference; the plugin is built for TypeDoc 0.28. `@doc-kit/cli` and `@doc-kit/generator-react` build the site, as in Getting started.","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev typedoc@0.28 @doc-kit/typedoc @doc-kit/cli @doc-kit/generator-react"}],"children":[]},{"kind":"section","id":"configure-typedoc","name":"Configure TypeDoc","title":"Configure TypeDoc","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Create `typedoc.config.mjs` next to your `package.json`:\n\n```mjs 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 it: the root of your repository\n  basePath: '.',\n  docKit: 'docs/api',\n};\n```\n\n* `plugin: [load]` passes the plugin itself, not its package name. TypeDoc\n  imports plugins named by a string from its own installation, where package\n  managers such as pnpm hide your project's dependencies, so passing `load`\n  works with any package manager.\n* `docKit` sets where the reference goes. With it set, TypeDoc skips its own\n  HTML output.\n* `basePath` makes the source links relative to your repository's root, so\n  they match your files on GitHub.\n\nEverything else, such as entry points, the `tsconfig` and which exports to\ninclude, is configured with TypeDoc's own options.","summary":"Create `typedoc.config.mjs` next to your `package.json`:","examples":[{"language":"mjs","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 it: the root of your repository\n  basePath: '.',\n  docKit: 'docs/api',\n};"}],"children":[]},{"kind":"section","id":"generate-the-reference","name":"Generate the reference","title":"Generate the reference","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"```bash\nnpx typedoc\n```\n\nTypeDoc finds `typedoc.config.mjs` in the working directory, and the plugin\nwrites the reference in TypeDoc's folder layout:\n\n```text\ndocs/api/\n├── functions/\n│   └── adopt.md\n├── interfaces/\n│   └── Kitten.md\n├── pages.json\n└── type-map.json\n```\n\n* A page per exported class, interface, enum, type alias, function and\n  variable, in `classes/`, `interfaces/`, `enums/`, `types/`, `functions/`\n  and `variables/`. Namespaces, and modules when you have several entry\n  points, get a page in `modules/`.\n* `type-map.json` maps each type name to its page, so doc-kit can link type\n  annotations to it.\n* `pages.json` lists the pages, for your site's navigation.\n\nThere's no page for the project itself: that one is yours to write, for\nexample as `docs/index.md`.\n\n> \\[!TIP]\n> The plugin writes into `docs/api/` without emptying it first. Delete the\n> folder before generating when you rename or remove exports, so their old\n> pages don't stay behind. Since it's generated, you can also leave it out of\n> version control.","summary":"TypeDoc finds `typedoc.config.mjs` in the working directory, and the plugin writes the reference in TypeDoc's folder layout:","examples":[{"language":"bash","displayName":null,"code":"npx typedoc"},{"language":"text","displayName":null,"code":"docs/api/\n├── functions/\n│   └── adopt.md\n├── interfaces/\n│   └── Kitten.md\n├── pages.json\n└── type-map.json"}],"children":[]},{"kind":"section","id":"from-doc-comments-to-markdown","name":"From doc comments to Markdown","title":"From doc comments to Markdown","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Take this source file:\n\n```ts displayName=\"src/index.ts\"\n/** A kitten, adopted or not. */\nexport interface Kitten {\n  /** The kitten's name. */\n  name: string;\n}\n\n/**\n * Adopts a kitten, once the paperwork is done.\n *\n * @param name - The kitten's name.\n * @param options - How to adopt it.\n * @param options.color - Coat color.\n * @param options.signal - Cancels the adoption.\n * @returns The adopted kitten.\n * @experimental\n */\nexport async function adopt(\n  name: string,\n  options: { color?: string; signal?: AbortSignal } = {}\n): Promise<Kitten> {\n  return { name };\n}\n```\n\nThe plugin writes `adopt()` as this page:\n\n```markdown displayName=\"docs/api/functions/adopt.md\"\n# `adopt(name[, options])`\n\n<!-- YAML\ntitle: \"Function: adopt()\"\nsource_link: src/index.ts#L17\n-->\n\n> [Stability: 1](documentation.html#stability-index) - Experimental\n\n- `name` {string} The kitten's name.\n- `options` {Object} How to adopt it. **Default:** `{}`.\n  - `color` {string} Coat color.\n  - `signal` {AbortSignal} Cancels the adoption.\n- Returns: {Promise<Kitten>} The adopted kitten.\n\nAdopts a kitten, once the paperwork is done.\n```\n\nIt's the Markdown you would write by hand, as described in\n[Writing documentation](./writing-docs.html):\n\n* The heading is the call, with `options` in brackets: it has a default\n  value, so it's optional.\n* The YAML comment holds the page title and the link to the source.\n* `@experimental` becomes a stability indicator.\n* The typed list holds each parameter's type and `@param` description, the\n  properties of `options` nested under it, and the return value with its\n  `@returns` description.\n* The summary follows, as the entry's description.\n\nOnce doc-kit builds it, `Promise<Kitten>` links to the `Kitten` page through\nthe type map, and `Promise` and `AbortSignal` link to MDN.\n\nOther tags follow the same pattern: `@deprecated` becomes a\n`Stability: 0 - Deprecated` indicator with its message, `@example` an\n\"Example\" section, and `{@link}` a link to its target. TypeDoc's `@remarks`\nand `@since` aren't rendered, so keep that text in the summary.\n\nDeclarations follow doc-kit's conventions too: a class gets a `Class:`\nheading, and a property an entry with a `Type:` item, named after its owner\nwith a lowercase first letter, such as `kitten.name`. The\n[`@doc-kit/typedoc` reference](./packages/typedoc.html#how-code-and-comments-are-rendered)\nlists every tag and declaration the plugin renders.","summary":"Take this source file:","examples":[{"language":"ts","displayName":"src/index.ts","code":"/** A kitten, adopted or not. */\nexport interface Kitten {\n  /** The kitten's name. */\n  name: string;\n}\n\n/**\n * Adopts a kitten, once the paperwork is done.\n *\n * @param name - The kitten's name.\n * @param options - How to adopt it.\n * @param options.color - Coat color.\n * @param options.signal - Cancels the adoption.\n * @returns The adopted kitten.\n * @experimental\n */\nexport async function adopt(\n  name: string,\n  options: { color?: string; signal?: AbortSignal } = {}\n): Promise<Kitten> {\n  return { name };\n}"},{"language":"markdown","displayName":"docs/api/functions/adopt.md","code":"# `adopt(name[, options])`\n\n<!-- YAML\ntitle: \"Function: adopt()\"\nsource_link: src/index.ts#L17\n-->\n\n> [Stability: 1](documentation.html#stability-index) - Experimental\n\n- `name` {string} The kitten's name.\n- `options` {Object} How to adopt it. **Default:** `{}`.\n  - `color` {string} Coat color.\n  - `signal` {AbortSignal} Cancels the adoption.\n- Returns: {Promise<Kitten>} The adopted kitten.\n\nAdopts a kitten, once the paperwork is done."}],"children":[]},{"kind":"section","id":"build-the-site","name":"Build the site","title":"Build the site","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Point doc-kit at the whole `docs/` folder, and at the type map:\n\n```mjs displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['html', 'orama-db'],\n\n  global: {\n    project: 'Kittens',\n    repository: 'you/kittens',\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n\n  metadata: {\n    typeMap: 'docs/api/type-map.json',\n  },\n};\n```\n\n* `input` reads the guides and the reference alike: `docs/**/*.md` includes\n  `docs/api/`.\n* `metadata.typeMap` links every type annotation naming one of your types to\n  its page, in the reference and in your guides.\n* `repository` (`owner/name`) turns the source links into links to your\n  files on GitHub.\n\nThe type map's paths are relative to the folder your `input` glob starts from,\nhere `docs/`:\n\n```json displayName=\"docs/api/type-map.json\"\n{\n  \"Kitten\": \"api/interfaces/Kitten\"\n}\n```\n\nThese paths have no extension, so type links need a host that serves\n`/api/interfaces/Kitten` from `Kitten.html`, as GitHub Pages, Netlify and\nCloudflare do, and Vercel with `cleanUrls`. See\n[Page URLs](./publishing.html#page-urls).\n\nIf the reference sits deeper, such as in `docs/reference/api/`, set the\nplugin's `docKitBasePath` option to `'reference/api'` so the paths still\nmatch.\n\nIn your guides, link to reference pages by their file, and name your types in\nbraces, as you would anywhere else:\n\n```markdown displayName=\"docs/index.md\"\n# Kittens\n\nCall [`adopt()`](./api/functions/adopt.md) to bring home a {Kitten}.\n```\n\nRun TypeDoc before each build, for example from a script in your\n`package.json`:\n\n```json displayName=\"package.json\"\n{\n  \"scripts\": {\n    \"docs\": \"typedoc && doc-kit generate\"\n  }\n}\n```\n\n`npm run docs` then builds the site into `out/`; preview it as in\n[Getting started](./getting-started.html).","summary":"Point doc-kit at the whole `docs/` folder, and at the type map:","examples":[{"language":"mjs","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['html', 'orama-db'],\n\n  global: {\n    project: 'Kittens',\n    repository: 'you/kittens',\n    input: ['docs/**/*.md'],\n    output: 'out',\n  },\n\n  metadata: {\n    typeMap: 'docs/api/type-map.json',\n  },\n};"},{"language":"json","displayName":"docs/api/type-map.json","code":"{\n  \"Kitten\": \"api/interfaces/Kitten\"\n}"},{"language":"markdown","displayName":"docs/index.md","code":"# Kittens\n\nCall [`adopt()`](./api/functions/adopt.md) to bring home a {Kitten}."},{"language":"json","displayName":"package.json","code":"{\n  \"scripts\": {\n    \"docs\": \"typedoc && doc-kit generate\"\n  }\n}"}],"children":[]},{"kind":"section","id":"building-the-sidebar","name":"Building the sidebar","title":"Building the sidebar","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Without [`navigation.sidebar`](./generators/html.html#sidebar), the site's\nsidebar lists every page in one \"API Documentation\" group. `pages.json` gives\nyou what you need to build your own: the name, kind, URL and category of each\nreference page.\n\n```json displayName=\"docs/api/pages.json\"\n[\n  { \"name\": \"Kitten\", \"kind\": \"Interface\", \"url\": \"/api/interfaces/Kitten\" },\n  { \"name\": \"adopt\", \"kind\": \"Function\", \"url\": \"/api/functions/adopt\" }\n]\n```\n\nTypeDoc categorizes the exports of each module and namespace separately: once\none of them has a `@category`, TypeDoc files the others under \"Other\" (its\n`defaultCategory` option). When none has one, their pages have no `category`,\nas above.\n\nRead the page list in your configuration, and turn it into sidebar groups.\nThis one makes a group per category, next to your guides:\n\n```mjs displayName=\"doc-kit.config.mjs\"\nimport { readFileSync } from 'node:fs';\n\nconst pages = JSON.parse(\n  readFileSync(new URL('./docs/api/pages.json', import.meta.url), 'utf8')\n);\n\n// A group per category, and \"Other\" for the pages without one\nconst categories = Object.groupBy(pages, ({ category }) => category ?? 'Other');\n\nexport default {\n  // ...\n\n  html: {\n    navigation: {\n      sidebar: [\n        {\n          groupName: 'Guides',\n          items: [{ label: 'Introduction', link: '/index' }],\n        },\n        ...Object.entries(categories).map(([groupName, entries]) => ({\n          groupName,\n          items: entries.map(({ name, url }) => ({\n            label: `\\`${name}\\``,\n            link: url,\n          })),\n        })),\n      ],\n    },\n  },\n};\n```\n\nThe configuration reads `pages.json` when it loads, so run TypeDoc first.\n[Customizing the site](./customization.html#navigation) covers the rest of the\nnavigation.","summary":"Without `navigation.sidebar`, the site's sidebar lists every page in one \"API Documentation\" group. `pages.json` gives you what you need to build your own: the name, kind, URL and category of each reference page.","examples":[{"language":"json","displayName":"docs/api/pages.json","code":"[\n  { \"name\": \"Kitten\", \"kind\": \"Interface\", \"url\": \"/api/interfaces/Kitten\" },\n  { \"name\": \"adopt\", \"kind\": \"Function\", \"url\": \"/api/functions/adopt\" }\n]"},{"language":"mjs","displayName":"doc-kit.config.mjs","code":"import { readFileSync } from 'node:fs';\n\nconst pages = JSON.parse(\n  readFileSync(new URL('./docs/api/pages.json', import.meta.url), 'utf8')\n);\n\n// A group per category, and \"Other\" for the pages without one\nconst categories = Object.groupBy(pages, ({ category }) => category ?? 'Other');\n\nexport default {\n  // ...\n\n  html: {\n    navigation: {\n      sidebar: [\n        {\n          groupName: 'Guides',\n          items: [{ label: 'Introduction', link: '/index' }],\n        },\n        ...Object.entries(categories).map(([groupName, entries]) => ({\n          groupName,\n          items: entries.map(({ name, url }) => ({\n            label: `\\`${name}\\``,\n            link: url,\n          })),\n        })),\n      ],\n    },\n  },\n};"}],"children":[]},{"kind":"section","id":"javascript-projects","name":"JavaScript projects","title":"JavaScript projects","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"TypeDoc reads JavaScript too, taking the types from its JSDoc comments, once\nTypeScript is allowed to: set `allowJs` (or `checkJs`) in your\n`tsconfig.json`, and point `entryPoints` at your JavaScript, such as\n`src/index.js`.\n\n```json displayName=\"tsconfig.json\"\n{\n  \"compilerOptions\": {\n    \"allowJs\": true\n  },\n  \"include\": [\"src\"]\n}\n```\n\nThe types then come from the JSDoc tags:\n\n```js displayName=\"src/index.js\"\n/**\n * Adopts a kitten, once the paperwork is done.\n *\n * @param {string} name The kitten's name.\n * @param {object} [options] How to adopt it.\n * @param {string} [options.color] Coat color.\n * @param {AbortSignal} [options.signal] Cancels the adoption.\n * @returns {Promise<{ name: string }>} The adopted kitten.\n * @experimental\n */\nexport async function adopt(name, options = {}) {\n  return { name };\n}\n```\n\nThis gives the same page as the TypeScript version, apart from the return\ntype, which reads as written: `{Promise<{ name: string }>}`. A `@typedef` of\nan object type gets a page of its own, as an interface would.","summary":"TypeDoc reads JavaScript too, taking the types from its JSDoc comments, once TypeScript is allowed to: set `allowJs` (or `checkJs`) in your `tsconfig.json`, and point `entryPoints` at your JavaScript, such as `src/index.js`.","examples":[{"language":"json","displayName":"tsconfig.json","code":"{\n  \"compilerOptions\": {\n    \"allowJs\": true\n  },\n  \"include\": [\"src\"]\n}"},{"language":"js","displayName":"src/index.js","code":"/**\n * Adopts a kitten, once the paperwork is done.\n *\n * @param {string} name The kitten's name.\n * @param {object} [options] How to adopt it.\n * @param {string} [options.color] Coat color.\n * @param {AbortSignal} [options.signal] Cancels the adoption.\n * @returns {Promise<{ name: string }>} The adopted kitten.\n * @experimental\n */\nexport async function adopt(name, options = {}) {\n  return { name };\n}"}],"children":[]},{"kind":"section","id":"going-further","name":"Going further","title":"Going further","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The [`@doc-kit/typedoc` reference](./packages/typedoc.html#options) lists the\nplugin's other options: `docKitMemberPages` gives each member of a large\noptions type a page of its own, `docKitReceivers` changes the name members\nare documented on, and `docKitUrlAdapter` keeps the URLs of an earlier site\nworking. To shape the rest of the site, continue with\n[Customizing the site](./customization.html).","summary":"The `@doc-kit/typedoc` reference lists the plugin's other options: `docKitMemberPages` gives each member of a large options type a page of its own, `docKitReceivers` changes the name members are documented on, and `docKitUrlAdapter` keeps the URLs of an earlier site working. To shape the rest of the site, continue with Customizing the site.","examples":[],"children":[]}]}