typedoc-vitepress-theme

typedoc-vitepress-theme

A typedoc-plugin-markdown theme that publishes Markdown pages compatible with VitePress.

What does it do?

• Presets relevant options of typedoc-plugin-markdown targetting VitePress Markdown.
• Auto generates a VitePress sidebar that can be referenced from the VitePress config.

What about VuePress?

This theme is also compatible with VuePress and the configuration is almost identical. However this theme supersedes previous VuePress TypeDoc plugins and is specifically targetted for VitePress.

See https://vitepress.dev/guide/what-is-vitepress#what-about-vuepress.

Installation

1. Install VitePress

https://vitepress.dev/guide/getting-started

2. Install plugin

Install the plugin in the same location as your VitePress installation.

typedoc and typedoc-plugin-markdown are required peer dependencies.

npm install typedoc typedoc-plugin-markdown@next typedoc-vitepress-theme@next --save-dev

Typical file structure

.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ └─ api (default out dir containing generated TypeDoc pages and typedoc-sidebar.json file)
└─ package.json (package.json project root)

Usage

Create a script that builds TypeDoc pages before bootstraping VitePress. The following is a guideline only and can be tailored as required.

1. Create a script to publish TypeDoc pages

"publish-typedoc": "typedoc --options typedoc.json"

typedoc.json

{
  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"]
}

2. Run the script before bootstrapping VitePress

"docs:dev": "npm run publish-typedoc && vitepress dev docs",
"docs:build": "npm run publish-typedoc && vitepress build docs"

3. Configure Navbar and Sidebar

A sidebar named typedoc-sidebar.json is auto-generated to the out directory. This can then be referenced in the config file to configure the sidebar.

docs/.vitepress/config.ts

import typedocSidebar from '../api/typedoc-sidebar.json';

module.exports = {
  themeConfig: {
    nav: [{ text: 'API', link: '/api/' }],
    sidebar: [
      {
        text: 'API',
        items: typedocSidebar,
      },
    ],
  },
};

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.

TypeDoc options

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 VitePress).

The following typedoc-plugin-markdown options are preset with the theme.

{
  "entryFileName": "index.md",
  "hideBreadcrumbs": true,
  "hidePageHeader": true,
  "out": "./docs/api"
}

Theme options

The following theme options are also exposed, but the defaults should work for most use cases.

--sidebar

sidebar.autoConfiguration

Set to false to disable sidebar generation. Defaults to true.

sidebar.format

The format of the sidebar. This option is exposed to enable backward compatibility with VuePress sidebars. Available options [vitepress vuepress1, vuepress2]. Defaults to vitepress.

{
  "sidebar": {
    "autoConfiguration": true,
    "format": "vitepress"
  }
}

--docsRoot

The VitePress docs folder root. Use ./ if no root folder specified. Defaults to ./docs.

--docsRoot <path/to/vitepress-docs/>

Frontmatter

Frontmatter can be added to pages by installing typedoc-plugin-frontmatter and adding to the plugin list.

{
  "plugin": [..., "typedoc-plugin-frontmatter"]
}

License

MIT