|
| 1 | +# `@doc-kit/typedoc` |
| 2 | + |
| 3 | +A [TypeDoc](https://typedoc.org) plugin writing the API reference of a TypeScript project as [doc-kit Markdown](../../docs/specification.md): one page per export, with doc-kit's signatures, typed lists, stability indices and source links, which doc-kit then builds into a site. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +Install it next to TypeDoc: |
| 8 | + |
| 9 | +```sh |
| 10 | +npm install --save-dev typedoc @doc-kit/typedoc |
| 11 | +``` |
| 12 | + |
| 13 | +Add it to your TypeDoc configuration, with its `doc-kit` output: |
| 14 | + |
| 15 | +```js |
| 16 | +// typedoc.config.mjs |
| 17 | +import { fileURLToPath } from 'node:url'; |
| 18 | + |
| 19 | +export default { |
| 20 | + // A path resolved from your project: TypeDoc resolves plugin names from |
| 21 | + // its own installation, which strict package managers keep apart |
| 22 | + plugin: [fileURLToPath(import.meta.resolve('@doc-kit/typedoc'))], |
| 23 | + entryPoints: ['src/index.ts'], |
| 24 | + outputs: [{ name: 'doc-kit', path: 'docs/api' }], |
| 25 | +}; |
| 26 | +``` |
| 27 | +
|
| 28 | +Then generate the reference, and point doc-kit at it: |
| 29 | +
|
| 30 | +```sh |
| 31 | +npx typedoc --options typedoc.config.mjs |
| 32 | +``` |
| 33 | +
|
| 34 | +```js |
| 35 | +// doc-kit.config.mjs |
| 36 | +export default { |
| 37 | + global: { input: ['docs/**/*.md'] }, |
| 38 | + metadata: { typeMap: 'docs/api/type-map.json' }, |
| 39 | +}; |
| 40 | +``` |
| 41 | +
|
| 42 | +`typedoc --watch` keeps the reference up to date as the sources change; only the pages that changed are written. |
| 43 | +
|
| 44 | +## Output |
| 45 | +
|
| 46 | +The output directory receives: |
| 47 | +
|
| 48 | +- A page per exported function, class, interface, type alias and variable: `Function.build.md`, `Interface.BuildOptions.md`, … |
| 49 | +- A page per member of the types in `docKitMemberPages`: `BuildOptions.input.md`, … |
| 50 | +- `type-map.json`, mapping type names to their pages, for doc-kit's `typeMap` to link `{Type}` annotations with. |
| 51 | +- `pages.json`, listing every page (name, kind, URL, `@category`, and the type of a member page) for the site to build its navigation from. |
| 52 | +
|
| 53 | +Other files in the directory (an `index.md` you write, for instance) are left alone. |
| 54 | +
|
| 55 | +## How comments are rendered |
| 56 | +
|
| 57 | +- Call signatures become doc-kit signatures: a `` `name(a[, b])` `` heading and a typed list of the parameters and return value, with `@param` and `@returns` descriptions. The properties of object parameters are nested in the list. |
| 58 | +- Properties become entries with a `Type:` item, and `@default` values. |
| 59 | +- `@deprecated` and `@experimental` become stability indices. |
| 60 | +- `@example`, `@see` and `@throws` follow the description. Block tags of your own (declared with TypeDoc's `blockTags`) are rendered as `**Tag:** content`. |
| 61 | +- `{@link}` and `{@linkcode}` link to the target's page or entry. |
| 62 | +
|
| 63 | +## Options |
| 64 | +
|
| 65 | +- `docKitBasePath` {string} The URL path the pages are served under. **Default:** the output directory's name (`/api`). |
| 66 | +- `docKitSiteUrl` {string} The URL of the site. Absolute links to it in comments become relative. |
| 67 | +- `docKitMemberPages` {string[]} Types whose members are each documented on a page of their own, such as a bundler's options. Their own page, the pages of the types extending them, and the parameters of their type list the members and link to their pages, rather than repeating their documentation. **Default:** `[]`. |
| 68 | +- `docKitReceivers` {Object} The name members of a type are documented on, by type name: `{ "PluginContext": "this" }` documents `this.resolve()`. **Default:** the type name in camelCase (`pluginContext.resolve()`). |
| 69 | +- `docKitEvents` {Object} Event emitters, mapped to the type mapping their event names to the arguments of their listeners (a tuple per event): `{ "Watcher": "WatcherEvents" }` documents `Event: 'change'` entries on `Watcher`'s page. **Default:** `{}`. |
| 70 | +- `docKitSignatureSources` {Object} Types whose members take their signatures from the members of the same name of another type, by type name, for members whose type is too generic to document (a plugin's hooks, for instance). **Default:** `{}`. |
| 71 | +- `docKitImportPaths` {Object} The import path of each entry point, by file. Pages of exports missing from the shortest import path say where they are exported from. **Default:** `{}`. |
| 72 | +- `docKitMemberAnchors` {boolean} Give members an anchor of their name alone (`#input`) besides doc-kit's anchor of their heading, to keep links of a previous site working. **Default:** `false`. |
0 commit comments