docusaurus-plugin-typedoc

A Docusaurus v2 plugin to build documentation with TypeDoc.

!CI

What does it do?

Generates static TypeDoc pages in Markdown with frontmatter as part of the Docusaurus build.

Installation

> Install Docusaurus in the root of your project and install the plugin dependencies in the same location as the Docusaurus website directory.

``shell
npm install typedoc typedoc-plugin-markdown docusaurus-plugin-typedoc --save-dev
`

Usage

$3

Add the plugin to docusaurus.config.js and specify the required options (see options).

`js
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',

// Plugin / TypeDoc options
{
entryPoints: ['../src/index.ts'],
tsconfig: '../tsconfig.json',
},
],
],
};
`

TypeDoc will be bootstraped with the Docusaurus start and build cli commands:

`javascript
"start": "docusaurus start",
"build": "docusaurus build",
`

Once built the docs will be available at /docs/api (or equivalent out directory).

$3

`
├── docusauruss-website
├── build/ (static site dir)
├── docs/
│ ├── api/ (compiled typedoc markdown)
├── docusaurus.config.js
├── package.json
├── sidebars.js
├──package.json
├──src (typescript source files)
├──tsconfig.json
`

Options

$3

To configure TypeDoc, pass any relevant TypeDoc options to the config.

At a minimum the entryPoints and tsconfig options will need to be set.

`js
entryPoints: ['../src/index.ts'],
tsconfig: '../tsconfig.json'
`

Additional TypeDoc plugins will need to be explicitly set:

`js
plugin: ['typedoc-plugin-xyz'];
`

#### Other config options

TypeDoc options can also be declared:

- Using a typedoc.json file.
- Under the typedocOptions key in tsconfig.json.

> Note: Options declared in this manner will take priority and overwrite options declared in docusaurus.config.js.

$3

Options specific to the plugin should also be declared in the same object.

| Name | Default | Description |
| :---------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| out | "api" | Output dir relative to docs dir (use . for no subdir). |
| includeExtension | true | Determines whether to preserve the .md extension in relative links. true is recommended as per Docusaurus documentation |
| frontmatter | null | Additional frontmatter options object. See Frontmatter. |
| sidebar.categoryLabel | API | The sidebar parent category label. |
| sidebar.collapsed | true | Whether the parent category is initially collapsed |
| sidebar.fullNames | false | Display full names with module path. |
| sidebar.position | auto | The position of the sidebar in the tree. |

$3

`js
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',
{
// TypeDoc options
entryPoints: ['../src/index.ts'],
tsconfig: '../tsconfig.json',
plugin: ['typedoc-plugin-xyz'],

// Plugin options
out: 'api-xyz',
sidebar: {
categoryLabel: 'API XYZ',
collapsed: false,
position: 0,
fullNames: true,
},
},
],
],
};
`

Recipes

$3

#### Sidebar

sidebars.js can be configured in following ways:

1. Generate the entire sidebar from file structure of your docs folder (default behaviour):

`js
module.exports = {
sidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' means the docs folder
},
],
};
`

2. Alternatively, if you wish to manually control other parts of your sidebar you can use a slice for the TypeDoc sidebar.

> note: sidebar.categoryLabel, sidebar.collapsed, and sidebar.position options are ignored with this implementation)

`js
module.exports = {
sidebar: {
'Category 1': ['doc1', 'doc2', 'doc3'],
API: [
{
type: 'autogenerated',
dirName: 'api', // 'api' is the 'out' directory
},
],
},
};
`

Please see https://docusaurus.io/docs/sidebar for sidebar documentation.

#### Navbar

A navbar item can be configured in themeConfig options in docusaurus.config.js:

`js
themeConfig: {
navbar: {
items: [
{
to: 'docs/api/', // 'api' is the 'out' directory
activeBasePath: 'docs',
label: 'API',
position: 'left',
},
],
},
},
`

Please see https://docusaurus.io/docs/api/themes/configuration#navbar-items for navbar documentation.

$3

By default the plugin will configure minimal required Frontmatter configuration.
Additionally required global Frontmatter options can be passed in using the frontmatter options object

docusaurus.config.js:

`js
plugins: [
[
'docusaurus-plugin-typedoc',
{
// .... other plugin option
frontmatter: {
pagination_prev: null,
pagination_next: null
}
]
]
`

$3

It is possible to build multi TypeDoc instances by passing in multiple configs with unique ids:

docusaurus.config.js

`js
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',
{
id: 'api-1',
entryPoints: ['../api-1/src/index.ts'],
tsconfig: '../api-1/tsconfig.json',
out: 'api-1',
},
],
[
'docusaurus-plugin-typedoc',
{
id: 'api-2',
entryPoints: ['../api-2/src/index.ts'],
tsconfig: '../api-2/tsconfig.json',
out: 'api-2',
},
],
],
};
`

$3

Watching files is supported by passing in the watch: true option see https://typedoc.org/guides/options/#watch.

Targetting the option in development mode only can be achieved using Node.js Environment Variables:

package.json

`json
"start": "TYPEDOC_WATCH=true docusaurus start",
"build": "TYPEDOC_WATCH=false docusaurus build",
`

docusaurus.config.js

`js
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',
{
entryPoints: ['../src/index.ts'],
tsconfig: '../tsconfig.json',
watch: process.env.TYPEDOC_WATCH,
},
],
],
};
`

$3

docusaurus.config.js

`js
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',
{
entryPoints: ['../packages/package-a', '../packages/package-b'],
entryPointStrategy: 'packages',
sidebar: {
fullNames: true,
},
},
],
],
};
``

License

MIT