Typedoc integration

Added in version 0.2

Djockey can integrate with TypeDoc to create an integrated documentation experience that combines the authoring power of Djockey with rich API references. For example, here in the Djockey docs, we can type [](:ts:DjockeyPlugin) and get DjockeyPlugin.

The core concept is to render TypeDoc normally inside your docs directory, treat its output as static files, and then create convenient link aliases into it.

1. Run TypeDoc

First, run TypeDoc on your project with JSON and HTML output. The JSON output can go anywhere, but the HTML must go inside your docs source directory next to your markup.

npx typedoc src/index.ts \
  --json docs/src/types.json \
  --out docs/src/api

2. Generate a link map

Djockey uses a link map file to figure out where to point links to. You generate a link map using a separate program called linkmapper-typedoc.

npm install --dev @djockey/linkmapper-typedoc
npx linkmapper-typedoc \
  docs/src/types.json \
  docs/src/typescript_link_map.json

3. Configure Djockey

Assuming your djockey.yaml is under docs…

link_mappings:
  - path: src/typescript_link_map.json
    url_root: api/

The path is relative to djockey.yaml. url_root should be the place you rendered TypeDoc’s HTML output to.

4. Link to your API docs

From here, you can write :ts:symbolName as a link destination to get a link into your TypeDoc API reference. If you need to disambiguate, for example to refer to a method on a specific class, you can add parent types as a prefix, like :ts:SomeClass.someMethod or :ts:namespace.SomeClass.someMethod.

If your link doesn’t have any text, the text will be populated automatically. So you can say [API reference for DjockeyPlugin](:ts:DjockeyPlugin) to customize the link text, or just [](:ts:DjockeyPlugin) to use the symbol name.