Skip to content

THEMES.md

Latest commit

 

History

History
150 lines (106 loc) · 3.93 KB

THEMES.md

File metadata and controls

150 lines (106 loc) · 3.93 KB
Raw

Markdown Themes

By default, the Markdown theme will attempt to render standard CommonMark, suitable for the majority of Markdown engines. It follows the same structure and file patterns as the default HTML theme (see typedoc-default-themes).

The plugin also comes packaged with some additional built-in themes and can also be extended with a custom theme.

Writing a custom markdown theme

The Markdown theme packaged with the plugin can also be extended with a custom Markdown theme using the standard TypeDoc theming pattern as per https://typedoc.org/guides/themes/.

Create a theme.js class

As per the theme docs create a theme.js file which TypeDoc will then attempt to load from a given location.

mytheme/custom-theme.js

const MarkdownTheme = require('typedoc-plugin-markdown/dist/theme');

class CustomMarkdownTheme extends MarkdownTheme.default {
  constructor(renderer, basePath) {
    super(renderer, basePath);
  }
}

exports.default = CustomMarkdownTheme;

Theme resources

By default the theme will inherit the resources of the Markdown theme (https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/src/resources).

These can be replaced and updated as required.

Building the theme

CLI

npx typedoc ./src --plugin typedoc-plugin-markdown --theme ./mytheme/custom-theme --out docs

API

const { Application } = require('typedoc');
const path = require('path');

const app = new Application({
  module: 'CommonJS',
  target: 'ES5',
  readme: 'none',
  theme: path.join(__dirname, 'mytheme', 'custom-theme'),
  plugin: 'typedoc-plugin-markdown',
});

app.generateDocs(app.expandInputFiles(['./src']), 'docs');

See https://typedoc.org/guides/installation/#node-module

Built-in themes

docusaurus / docusaurus2

The --out path is assumed be a Docusaurus docs directory.

Output

root-directory
├── docs
│   ├── myapi
│   |   ├── classes
│   │   ├── enums
│   │   ├── interfaces
│   │   ├── index.md
│   │
└── website
    ├── sidebars.json

Adding links in siteconfig

Manually add the index page to headerLinks in the siteConfig.js to access the api from header.

headerLinks: [
  { doc: "myapi/index", label: "My API" },
],

vuepress

  • Adds Front Matter to pages.

  • The --out path is assumed be a Vuepress docs directory.

  • Will create:

    • .vuepress/api-sidebar.json to be used with sidebar.
    • .vuepress/api-sidebar-relative.json to be used with multiple sidebars.
    • .vuepress/config.json

Examples

const apiSideBar = require('./api-sidebar.json');

// Without groups
module.exports = {
  themeConfig: {
    sidebar: ['some-content', ...apiSideBar],
  },
};

// With groups
module.exports = {
  themeConfig: {
    sidebar: ['some-content', { title: 'API', children: apiSideBar }],
  },
};
const apiSideBarRelative = require('./api-sidebar-relative.json');

// Multiple sidebars
module.exports = {
  themeConfig: {
    sidebar: {
      '/guide/': ['some-content'],
      '/api/': apiSideBarRelative,
      '/': ['other'],
    },
  },
};

bitbucket

Note: this theme applicable to Bitbucket Cloud. If using Bitbucket Server please use the --namedAnchors argument to fix anchor links.

  • Parses internal anchor links to support Bitbucket's internal anchor linking.