docusaurus-plugin-typedoc

docusaurus-plugin-typedoc

A Docusaurus plugin to build TypeScript API documentation with TypeDoc.

Contents

• What does it do?
• Installation
• Usage
• Options
• Sidebar
• Other configuration
• License

What does it do?

• Presets relevant options of typedoc-plugin-markdown.
• Runs TypeDoc from the Docusaurus CLI.

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',

      // Plugin / TypeDoc options
      {
        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

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.

Sidebar

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/',  // '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.

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