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 renders TypeScript API documentation as Markdown.

What does it do?

By default, TypeDoc will render API documentation as a webpage, e.g. HTML files.

The plugin replaces the default HTML theme with a built-in Markdown theme and exposes some additional options. This is useful if documentation is required to be included in project README files, Wikis and static site generators.

Installation

Please note this pre-release version may contain breaking changes within the same semantic version.

TypeDoc and Prettier are both required peer dependencies.

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

Usage

The plugin needs to be specified using the plugin argument:

command-line

typedoc --plugin typedoc-plugin-markdown

typedoc.json

{
  "plugin": ["typedoc-plugin-markdown"]
}

Options

The following options can be used in addition to relevant TypeDoc options (please note that TypeDoc options specific to the HTML theme will be ignored).

Please see options guide for more detailed descriptions of available plugin options.

Below is a summary of the available options:

--outputFileStrategy "members" | "modules"

Determines how output files are generated. Defaults to members. more »

--includeFileNumberPrefixes boolean

Prefixes generated files and folders with number prefixes. Defaults to false. more »

--flattenOutputFiles boolean

Flatten output files without folders. Defaults to false. more »

--entryFileName string

The file name of the entry page. Defaults to README.md. more »

--indexFileName string

The file name the seperate index page. Defaults to API.md. more »

--indexPageTitle string

The title of API index page. Defaults to undefined. more »

--skipIndexPage boolean

Skips generation of a seperate API index page. Defaults to false. more »

--excludeGroups boolean

Excludes grouping by reflection kind so all members are rendered and sorted at the same level. Defaults to false. more »

--hidePageHeader boolean

Do not print page header. Defaults to false.

--hidePageTitle boolean

Do not print page title. Defaults to false.

--hideKindPrefix boolean

Do not print the kind label as a title prefix. Defaults to false.

--hideBreadcrumbs boolean

Do not print breadcrumbs. Defaults to false.

--hideInPageTOC boolean

Do not render in-page table of contents items. Defaults to false.

--hideHierarchy boolean

Do not print reflection hierarchy. Defaults to false.

--identifiersAsCodeBlocks boolean

Format signature and declaration identifiers in code blocks. Defaults to false. more »

--propertiesFormat "list" | "table"

Specify the render style of properties groups for interfaces and classes. Defaults to list.

--enumMembersFormat "list" | "table"

Specify the render style of Enum members. Defaults to list.

--typeDeclarationFormat "list" | "table"

Specify the render style for type declaration members. Defaults to list.

--tocFormat "list" | "table"

Render TOC either as a simple list or a table with a description. Defaults to list.

--baseUrl string

Specifies the base url for internal link. If omitted all urls will be relative. Defaults to undefined.

--anchorFormat "lowercase" | "slug" | "none"

The anchor format to use when linking to internal symbols. Defaults to lowercase.

--anchorPattern string

The anchor pattern to use when linking to internal symbols. Defaults to undefined. more »

--namedAnchors boolean

Use HTML named anchors for engines that do not automatically assign header ids. Defaults to false.

Adding Frontmatter

If frontmatter is required for adding further metadata please use typedoc-plugin-frontmatter.

Output formatting

Generated Markdown is now parsed with Prettier which is backed by the remark-parse package. Parsing documents with Prettier has several benefits:

• Produces a consistent format.
• Removes unnecessary escape characters.
• Formats code blocks inside comment fenced blocks.

Any prettier configuration files discovered will be passed as options to the parser.

In addition all test files are linted with markdownlint.

Contributing

Contributions and suggestions are welcome. Please see the contributing guidelines for further details.

License

MIT