docusaurus-plugin-typedoc-api

A Docusaurus plugin for generating source code /api/* routes, powered by TypeDoc.

The plugin has been designed to document your public API by default (anything exported from a package's entry point), so any private, protected, or internal code will not be generated.

Requirements

• typescript >= v4
• @docusaurus/core >= v2.0.0-beta.18
• @docusaurus/preset-classic >= v2.0.0-beta.18

Examples

• Boost - https://boostlib.dev/api

Installation

yarn add --dev docusaurus-plugin-typedoc-api

Open your docusaurus.config.js and make the following changes:

• Add a link to the API route under themeConfig.navbar.items and themeConfig.footer.links (if desired).

1module.exports = {
2  // ...
3  themeConfig: {
4    // ...
5    navbar: {
6      // ...
7      items: [
8        // ...
9        {
10          to: 'api',
11          label: 'API',
12          position: 'left',
13        },
14      ],
15    },
16  },
17};

• Configure the plugin in your plugins list. The projectRoot and packages options are required.

1module.exports = {
2  // ...
3  plugins: [
4    [
5      'docusaurus-plugin-typedoc-api',
6      {
7        projectRoot: path.join(__dirname, '..'),
8        // Monorepo
9        packages: ['packages/example', 'packages/other'],
10        // Polyrepo
11        packages: ['.'],
12      },
13    ],
14  ],
15};

Configuration

The following options are available to the plugin:

• projectRoot (string) - Absolute path to the project root where tsconfig.json is located. (Required)
• packages ((string | PackageConfig)[]) - List of packages relative to the project root. (Required)
• banner (string) - Banner message to display at the top of the index page. Supports HTML.
• changelogName (string) - Name of the changelog file within a package. Defaults to CHANGELOG.md.
• changelogs (boolean) - Include and render the changelog file from every package. Defaults to false.
• exclude (string[]) - List of glob patterns to exclude unwanted packages. This is necessary when using TypeScript project references.
• gitRefName (string) - GitHub repository ref name to point the API links to. Defaults to master.
• minimal (boolean) - Render a minimal layout and reduce the amount of information displayed. Defaults to false.
• packageJsonName (string) - Name of the package.json file. Defaults to package.json.
• readmeName (string) - Name of the readme file within a package. Defaults to README.md.
• readmes (boolean) - Include and render the readme file from every package. Defaults to false.
• removeScopes (string[]) - Package scopes and prefixes to remove when displaying the package name in the sidebar and index. For example, boost will remove @boost/ and boost-.
• sortPackages ((a, d) => number) - Function to sort the package list in the sidebar and on the index page. Defaults to alphabetical.
• sortSidebar ((a, d) => number) - Function to sort the categories and items within each sidebar, excluding "Overview" and "Changelog". Defaults to alphabetical.
• tsconfigName (string) - Name of the TypeScript config file in the project root. Defaults to tsconfig.json.
• typedocOptions (object) - TypeDoc options to pass to the compiler. Only supports a small subset of options, primarily around visibility exclusion.

Packages

The packages option has been designed to support multiple packages, with multiple entry points per package. By default the option accepts a list of strings, where each value is a relative path to a package folder, and a default entry point of src/index.ts.

1module.exports = {
2  packages: ['packages/core', 'packages/react'],
3};

However, an object can be provided to customize the entry point. All entry point file paths are relative to the package folder, and support 2 formats:

• Index imports - Consumers can only import from the package index. This is typically an entry point like src/index.ts.
• Deep imports - Consumers can import anything from the package using its file path. Glob the entire package by only passing the folder name like src/. (This is useful for component libraries)

1module.exports = {
2  packages: [
3    'packages/core',
4    {
5      path: 'packages/react',
6      // Index only imports allowed
7      // import {} from 'package'
8      entry: 'src/index.tsx',
9      // Deep imports allowed
10      // import {} from 'package/some/nested/file'
11      entry: 'src/',
12    },
13  ],
14};

When not using deep imports, multiple entry points can be defined by passing a map of objects to entry, where each key is a sub-path that can be imported from the package (excluding the index). Each entry object requires a path and a label, which is used for categorizing and sidebars.

1module.exports = {
2  packages: [
3    'packages/core',
4    {
5      path: 'packages/react',
6      entry: {
7        // import {} from 'package'
8        index: 'src/index.tsx',
9        // import {} from 'package/client'
10        client: { file: 'src/client.tsx', label: 'Client' },
11        // import {} from 'package/server'
12        server: { file: 'src/server.tsx', label: 'Server' },
13        // import {} from 'package/server/test'
14        'server/test': { file: 'src/server/test-utils.tsx', label: 'Server test utils' },
15      },
16    },
17  ],
18};

Index entry points don't require a label, so a file path can be passed directly.

Linking

This plugin supports API and documentation linking within source code docblocks via the @apilink and @doclink tokens respectively. This works in a similar fashion to TypeDoc's @link resolution, but also supports Docusaurus versioning and routing patterns.

@apilink

When linking to other APIs, you must reference them by class name, function name, property, etc, instead of the actual /api route.

1# Maps to /api/<package>/class/Registry#register
2{@apilink Registry.register}
3{@apilink Registry.register | Text to use as the label}

@doclink

When linking to documentation pages, you must reference the article by its URL identifier without the /docs prefix.

1# Maps to /docs/commands/setup
2{@doclink commands/setup}
3{@doclink commands/setup | Text to use as the label}

Versioning

This plugin supports API versioning by piggy-backing off the built-in docs versioning implementation, which is a requirement for this to work correctly.

To begin, version your docs with the built-in command:

1yarn docusaurus docs:version 1.2.3

Once the markdown files are generated, run our versioning command with the same version used previously:

1yarn docusaurus api:version 1.2.3

This will create multiple JSON files in the versioned_docs/version-1.2.3 directory. Be sure to commit these files to your repo.

When versioning, the current state of your branch will be used as that version's API. To update/regenerate old versions, you'll need to checkout an old commit, re-version, and copy the generated files to the latest branch.

Navigation

Our API is unable to use the docsVersionDropdown navigation type, as it's hardcoded in Docusaurus core. However, you can create a custom version dropdown like so:

1const versions = require('./versions.json');
2
3module.exports = {
4  // ...
5  themeConfig: {
6    // ...
7    navbar: {
8      // ...
9      items: [
10        // ...
11        {
12          type: 'dropdown',
13          to: 'api',
14          label: 'API',
15          position: 'left',
16          items: [
17            { label: 'Next', to: 'api/next' },
18            ...versions.map((version, i) => ({
19              label: version,
20              to: i === 0 ? 'api' : `api/${version}`,
21            })),
22          ],
23        },
24      ],
25    },
26  },
27};

This workaround isn't perfect and may be buggy. Use at your own risk!

Caveats

• Each version in versioned_docs (or versions.json) must contain the generated API JSON files, otherwise the build will fail.
• The header/footer API links are not version aware, as their values are static.
• We suggest only versioning major versions, as the size of these JSON files and the webpack build will get very large very fast.

Comparison

There's another plugin called docusaurus-plugin-typedoc, that offers a similar solution. However, there are many differences between that package and this one, with the biggest being that theirs generates markdown files and /docs/api/... styled routes, while ours renders custom React pages with /api/... styled routes. Some other differences are:

• An index of all packages.
• Readme inclusion and rendering.
• Custom styles, sections, and headings.
• Multiple function and method signatures.
• Versioning!
• And probably more....