typedoc-plugin-markdown

What is typedoc-plugin-markdown?

The typedoc-plugin-markdown npm package is a plugin for TypeDoc that allows you to generate Markdown documentation from TypeScript projects. It extends TypeDoc's capabilities by providing support for various Markdown formats, making it easier to integrate with static site generators and other documentation tools.

What are typedoc-plugin-markdown's main functionalities?

Generate Markdown Documentation

This configuration file for TypeDoc uses the typedoc-plugin-markdown to generate Markdown documentation. The 'out' option specifies the output directory, and various 'exclude' options are used to filter out unnecessary parts of the documentation.

module.exports = {
  plugins: ['typedoc-plugin-markdown'],
  out: 'docs',
  mode: 'file',
  includeDeclarations: true,
  excludeExternals: true,
  excludePrivate: true,
  excludeProtected: true,
  excludeNotExported: true,
  readme: 'none'
};

Support for Custom Themes

This configuration demonstrates how to use a custom theme with the typedoc-plugin-markdown. The 'theme' option is set to 'custom-theme', which allows you to customize the look and feel of the generated Markdown documentation.

module.exports = {
  plugins: ['typedoc-plugin-markdown'],
  out: 'docs',
  theme: 'custom-theme',
  includeDeclarations: true,
  excludeExternals: true,
  excludePrivate: true,
  excludeProtected: true,
  excludeNotExported: true,
  readme: 'none'
};

Integration with Static Site Generators

This configuration shows how to set up the typedoc-plugin-markdown for integration with static site generators. The 'entryPoints' option specifies the entry points for the documentation, and 'entryPointStrategy' is set to 'expand' to include all relevant files.

module.exports = {
  plugins: ['typedoc-plugin-markdown'],
  out: 'docs',
  mode: 'file',
  includeDeclarations: true,
  excludeExternals: true,
  excludePrivate: true,
  excludeProtected: true,
  excludeNotExported: true,
  readme: 'none',
  entryPoints: ['src/index.ts'],
  entryPointStrategy: 'expand'
};

Other packages similar to typedoc-plugin-markdown

typedoc

TypeDoc is a documentation generator for TypeScript projects. While it primarily generates HTML documentation, it can be extended with plugins like typedoc-plugin-markdown to support other formats. TypeDoc is the core tool that typedoc-plugin-markdown builds upon.

documentation

The documentation package is a documentation generator for JavaScript and TypeScript projects. It supports multiple output formats, including HTML and Markdown. Compared to typedoc-plugin-markdown, it offers a more general approach to documentation generation and is not specifically tailored for TypeScript.

jsdoc

JSDoc is a popular documentation generator for JavaScript projects. It can be used with TypeScript through type annotations and supports various output formats, including Markdown. While it is more commonly used for JavaScript, it can be adapted for TypeScript projects, making it a versatile alternative to typedoc-plugin-markdown.

README

typedoc-plugin-markdown

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.

What it does?

The plugin will replace the default HTML theme with a built-in Markdown theme, and expose some additional arguments.

Installation

npm install --save-dev typedoc typedoc-plugin-markdown

Usage

$ node_modules/.bin/typedoc --plugin typedoc-plugin-markdown [args]

Note:

• The --plugin arg is optional - if omitted all installed plugins will run.
• If using with the default HTML theme or other themes, use --plugin none to switch the plugin off.

Arguments

Configuring a theme

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. The plugin also comes packaged with some additional built-in themes and can be extended with a custom theme.

• --theme
  
  • markdown Standard Markdown theme (default).
  • docusaurus Adds Front Matter header to pages, and attempts to update sidebars.json.
  • vuepress Adds Front Matter header to pages, and configures vuepress configs.
  • bitbucket Parses internal anchor links to support Bitbucket's internal anchor linking.
  • path/to/theme Path to a custom theme.

Configuring output

• --namedAnchors
  Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids.
• --hideSources
  Do not print source file link rendering.
• --hideBreadcrumbs
  Do not print breadcrumbs.

Custom 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 that extends the Markdown theme, and TypeDoc will then attempt to load from a given location.

custom-theme-dir/theme.js

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

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

exports.default = CustomMarkdownTheme;

Update resources

If used with the plugin, the theme will inherit the resources of the Markdown theme (https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/src/resources), rather than the default theme. These can be overdidden by shadowing (or adding new) resources in the custom theme directory.

The resources are based on and follow the same structure as typedoc-default-themes

Building the theme

CLI

node_modules/.bin/typedoc ./src --theme ./custom-theme-dir --out docs

API

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

const app = new Application({
  theme: path.join(__dirname, 'custom-theme-dir'),
  plugin: 'typedoc-plugin-markdown',
});

const project = app.convert(app.expandInputFiles(['src']));
app.generateDocs(project, 'docs');

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

License

MIT