docusaurus-plugin-typedoc
A Docusaurus plugin to build TypeScript API documentation with TypeDoc.
Contents
What does it do?
Installation
Install Docusaurus in the root of your project and install the plugin dependencies in the same location as the Docusaurus website directory.
typedoc and typedoc-plugin-markdown are peer dependencies.
npm install docusaurus-plugin-typedoc typedoc typedoc-plugin-markdown@next --save-dev
Usage
Add the plugin to docusaurus.config.js
and specify the required options (see options).
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',
{
entryPoints: ['../src/index.ts'],
tsconfig: '../tsconfig.json',
},
],
],
};
TypeDoc will be bootstraped with the Docusaurus start
and build
cli commands:
"start": "docusaurus start",
"build": "docusaurus build",
Once built the docs will be available at http://localhost:3000/docs/api
(or equivalent out directory).
Typical directory structure:
├── docusaurus-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
TypeDoc options
Options can be declared:
- Passing arguments via the command line.
- Using a
typedoc.json
file. - Under the
typedocOptions
key in tsconfig.json
.
Please see https://typedoc.org/options/configuration for general TypeDoc option configuration.
The following TypeDoc / Markdown plugin options can be passed to config:
- typedoc options (HTML specific output options that will be ignored).
- typedoc-plugin-markdown options (Some options are already preset to target Docusaurus).
The following typedoc-plugin-markdown options are preset with the plugin.
{
"out": "./docs/api",
"hideInPageTOC": true,
"hideBreadcrumbs": true,
"hidePageHeader": true,
"entryFileName": "index.md"
}
Plugin options
Options specific to the plugin should also be declared in the same object.
sidebar.autoConfiguration
Set to false
to disable sidebar generation. Defaults to true
.
sidebar.filteredIds
Ids of pages to be filtered from the sidebar. This would typically be used to filter README or index pages from the sidebar.
sidebar.pretty
Pretty format the sidebar JSON.
Previous versions of this plugin recommended an autogenerated
sidebar configuration. However we have decided it is more deterministic and configurable to use a manual sidebar configuration with a generated sidebar file.
A docusaurus sidebar file typedoc-sidebar.cjs
is published to the relevant output directory along with the generated markdown documentation.
This file should be referenced in sidebars.js
using a sidebar slice and can be configured in following ways:
- Display sidebar on the root:
module.exports = {
typedocSidebar: require('./docs/api/typedoc-sidebar.cjs'),
};
- Display the sidebar inside a category:
module.exports = {
typedocSidebar: {
'Typedoc Docs': require('./docs/api/typedoc-sidebar.cjs'),
},
};
- Display the sidebar inside a linked category
Note the linked category page can be removed from sidebar using sidebar.filteredIds
.
module.exports = {
typedocSidebar: [
{
type: 'category',
label: 'Typedoc Docs',
link: {
type: 'doc',
id: 'api/index',
},
items: require('./docs/api/typedoc-sidebar.cjs'),
},
],
};
Please see https://docusaurus.io/docs/sidebar for sidebar documentation.
Other configuration
Navbar
A navbar item can be configured in themeConfig
options in docusaurus.config.js
:
themeConfig: {
navbar: {
items: [
{
to: 'docs/api/',
activeBasePath: 'docs',
label: 'API',
position: 'left',
},
],
},
},
Please see https://docusaurus.io/docs/api/themes/configuration#navbar-items for navbar documentation.
Multi instance
It is possible to build multi TypeDoc instances by passing in multiple configs with unique ids:
docusaurus.config.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',
},
],
],
};
sidebars.js
module.exports = {
typedocSidebar: {
'API 1': require('./docs/api-1/typedoc-sidebar.cjs'),
'API 2': require('./docs/api-2/typedoc-sidebar.cjs'),
},
};
Watch mode
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
"start": "TYPEDOC_WATCH=true docusaurus start",
"build": "TYPEDOC_WATCH=false docusaurus build",
docusaurus.config.js
module.exports = {
plugins: [
[
'docusaurus-plugin-typedoc',
{
entryPoints: ['../src/index.ts'],
tsconfig: '../tsconfig.json',
watch: process.env.TYPEDOC_WATCH,
},
],
],
};
Frontmatter
To add frontmatter to page please use typedoc-plugin-frontmatter and add options exposed by the plugin to the config.
License
MIT