typedoc-plugin-markdown turns TypeDoc output into files a repository can hold

One output format, eight packages around it

The premise of this repository is a single decision: TypeScript API documentation should be Markdown. The plugin that does it, typedoc-plugin-markdown, is described as a TypeDoc plugin that generates TypeScript API documentation as Markdown, and the repository overview says it contains the core Markdown plugin, utility plugins for frontmatter and remark transforms, target-specific themes for wiki and static-site workflows, and a Docusaurus plugin that can run TypeDoc inside the Docusaurus lifecycle.

The package table makes the structure explicit. There is the core plugin, two utility plugins, four themes, and one integration package:

- typedoc-plugin-markdown, the core TypeDoc plugin that generates Markdown - typedoc-plugin-frontmatter, which adds configurable YAML frontmatter to the output - typedoc-plugin-remark, which runs remark plugins over the output - typedoc-github-wiki-theme and typedoc-gitlab-wiki-theme, for wiki targets - typedoc-vitepress-theme and typedoc-docusaurus-theme, for static site targets - docusaurus-plugin-typedoc, which runs TypeDoc inside the Docusaurus lifecycle

Each package has its own README and its own changelog, and the README's advice on where to start is explicit: begin with typedoc-plugin-markdown for the core Markdown output, then add the package that matches where you publish your docs.

That is a sensible structure. The expensive part of the project, parsing and reflecting a TypeScript API, is done once, and the parts that differ between destinations are small, isolated and independently versioned.

The licence is MIT, the documentation site is typedoc-plugin-markdown.org, and the last push to the main branch was on 2026-10-19.

Why Markdown instead of TypeDoc's own HTML

TypeDoc can already produce HTML, so the question a team has to answer is why route around that.

The answer is that Markdown output changes where the documentation pipeline lives. HTML documentation needs a host: a static site you build and deploy, or a documentation service you run. Markdown can simply be written into the repository, committed, reviewed in a pull request, and read on the hosting platform you already use.

That has consequences a team notices. Generated Markdown can be diffed, so a change in a public API shows up as a reviewable change rather than as a rebuild. It can be processed by the same remark and static site toolchain as the rest of your documentation, so headings, links and syntax highlighting are handled once for the whole site. And it can be published to a wiki, where the commit history is the version history.

The trade is that you give up TypeDoc's own rendering, which is where the built-in HTML output is strongest, and you take on a build step. A team whose documentation is already static-site generated has that step. A team whose documentation is currently a TypeDoc HTML page that nobody links to has to add one.

The frontmatter plugin exists because static site generators want metadata, and the remark plugin exists because the Markdown should go through the same processing as hand-written pages. Both are small problems that a Markdown output creates, and both are solved inside this repository rather than by every consumer.

The themes decide where the documentation is published

Four packages exist to make the Markdown output fit a specific destination, and the differences between them are about what the target expects rather than about the documentation itself.

The two wiki themes target GitHub Wiki and GitLab Wiki. Those platforms have their own conventions for how a page is named, how the home page is chosen and how navigation works between pages, and a theme exists to emit Markdown that matches those conventions rather than a set of loose files that the platform renders awkwardly.

The two static site themes target VitePress and Docusaurus. These are the mainstream choices for a documentation site built around Markdown, and each has its own front matter conventions, its own component vocabulary and its own build lifecycle, which is why a theme exists for each rather than one theme with a flag.

The eighth package is different in kind. docusaurus-plugin-typedoc does not generate Markdown for Docusaurus, it runs TypeDoc inside the Docusaurus lifecycle. That distinction decides who owns the build. With the core plugin plus the Docusaurus theme, you run TypeDoc yourself, get a folder of Markdown, and hand it to the site build. With docusaurus-plugin-typedoc, the site build invokes TypeDoc, so the documentation is always regenerated with the site and never goes stale in the repository.

A team that wants generated docs committed alongside the code and a team that wants them built on every deploy are making different choices, and the package list covers both.

Frontmatter, remark and the post-processing chain

The two utility plugins work on the output after the core plugin has produced it, and they are the reason a Markdown pipeline can be treated as a pipeline rather than a single step.

typedoc-plugin-frontmatter adds configurable YAML frontmatter to the Markdown output. That is the metadata a static site generator reads: page title, sidebar position, weight, edit URL, and whatever else the site expects. Without it, every generated page has to be patched after the fact, and a patch that runs on every build is a script somebody has to maintain.

typedoc-plugin-remark runs remark plugins on the Markdown output. remark is the processor ecosystem for Markdown, and it is what lets the generated documentation be treated exactly like a hand-written page: link rewriting with remark-github, heading anchor insertion with remark-insert-headings, and MDX handling with remark-mdx are all visible in the repository's own dependencies.

The ordering question is the one to think about. Frontmatter has to be added before the site generator reads the file, and remark transforms generally run on the body, so the natural pipeline is TypeDoc, then frontmatter, then remark, then the site. The repository is set up for that with the devtools packages and a docs script that regenerates the per-package READMEs and tables of contents, which is how a monorepo of eight packages keeps its overview pages in step with the code.

The build scripts show the shape of the pipeline. The root package.json runs npm run build --workspaces --if-present to build every package, the same pattern for test, test:update and lint, and the release script is npx changeset publish.

Changesets, commitlint and a release every few weeks

The release process is visible in the repository and it is the part that tells you how the project is run.

Versions are managed with changesets, since the repository has a .changeset directory and the release script is npx changeset publish. The publishing step runs after prerelease, which runs build-all, so the built artefacts are what gets published.

Commit messages are checked. The repository carries commitlint.config.cjs and a conventional commit configuration, with husky installing the hooks through the prepare script, so the commit format is enforced before it reaches the changelog.

The release history shows the effect. Version 4.13.1 was published on 2026-09-18, 4.14.0 on 2026-10-13 and 4.14.1 on 2026-10-19, the same day as the push to the main branch. Three releases in a month is a fast train for a documentation tool, and it is worth expecting your pinned version to move.

The linting stack is broad, which is consistent with a repository that publishes generated documentation and hand-written documentation side by side: eslint with its flat config, prettier with a plugin that organises imports, markdownlint for the Markdown itself, and a devtools workspace with shared helpers and testing packages.

The repository also carries the files a project with external contributors is expected to have, namely a contributing guide, a code of conduct, a security policy, an AGENTS.md and a CLAUDE.md for coding agents, and a commitlint configuration.

When the Markdown route is the wrong one

There are clear cases where this plugin is the wrong choice, and they are worth naming before you install eight packages.

The first is when you have one documentation consumer and it is TypeDoc's own HTML. The HTML output is the mature path, it needs no extra package, and adding Markdown to it means adding a build step and a hosting decision. The plugin is for people who want the files, not for people who want pages.

The second is when your documentation is not TypeScript API documentation. This is an API documentation generator for TypeDoc, so a project whose public interface is a CLI, a library written in another language, or a protocol described in prose will not benefit from it at all.

The third is a process objection. Eight packages, four of which are themes for platforms you may not use, is a fair amount of surface for a documentation pipeline, and the maintenance question is real: a plugin that follows TypeDoc's own version will need upgrading whenever TypeDoc moves, and the monorepo's release cadence suggests it will move.

The fourth is the case where the documentation has to be generated from a Docusaurus site that already owns the build, and in that situation docusaurus-plugin-typedoc is the right member of the family rather than the core plugin plus a theme.

What the plugin does well is narrow and real: it turns a TypeScript API into Markdown files that a repository can hold, a reviewer can read and a static site can publish, without anyone maintaining a separate documentation application.

Editorial conclusion

Adopt typedoc-plugin-markdown when you want API documentation that lives as Markdown in your repository, is reviewable in a pull request, and can be published to a wiki or a static site without a separate documentation service. Do not adopt it if you are happy with TypeDoc's built-in HTML output, or if your documentation must be generated from a Docusaurus site that already owns the build. Before you commit, read the options page on typedoc-plugin-markdown.org, because the difference between the core plugin, the themes and the Docusaurus plugin decides where your documentation pipeline lives, and note that the latest release, 4.14.1, shipped on 2026-10-19 alongside a push to the main branch.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. typedoc2md/typedoc-plugin-markdown on GitHub