Remark Plugins Usage

Useful Plugins

Here are a selection of remark plugins that might be useful. For a full list please visit the remark plugins page

remark-mdx

If you are using MDX, this plugin is required to correctly parse to MDX.


npm install remark-mdx --save-dev


pnpm add remark-mdx --save-dev


yarn add remark-mdx --dev


bun add remark-mdx --dev

typedoc.json


{
  "remarkPlugins": ["remark-mdx"]
}

remark-github

https://github.com/remarkjs/remark-github

Links references to commits, issues, and users in the same way that GitHub does in comments.


npm install remark-github --save-dev


pnpm add remark-github --save-dev


yarn add remark-github --dev


bun add remark-github --dev

typedoc.json


{
  "remarkPlugins": ["remark-github", { "repository": "myorg/myrepo" }]
}

remark-toc

https://github.com/remarkjs/remark-toc

Adds inline table of contents to pages.

Note: Also requires remark-insert-headings to add insert placeholder heading.


npm install remark-insert-headings remark-toc --save-dev


pnpm add remark-insert-headings remark-toc --save-dev


yarn add remark-insert-headings remark-toc --dev


bun add remark-insert-headings remark-toc --dev

typedoc.json


{
  "remarkPlugins": [
    ["remark-insert-headings", { "text": "Contents" }],
    ["remark-toc", { "maxDepth": 2 }]
  ]
}

Example Configuration

The following example shows how you might conditionally use the above plugins in your typedoc.json.

This is for illustration purposes only, and you can use any combination of plugins you like.

typedoc.json


{
  "plugin": ["typedoc-plugin-markdown", "typedoc-plugin-remark"],
  "remarkPlugins": [
    // Apply remark-mdx and remark-github to all files.
    {
      "applyTo": "*",
      "plugins": [
        "remark-mdx",
        ["remark-github", { "repository": "myorg/myrepo" }]
      ]
    },
    // Apply remark-toc to Readme page and members kinds of Document, Class and Interface only.
    {
      "applyTo": ["Readme", "Document", "Class", "Interface"],
      "plugins": [
        // remark-insert-headings is additionally required
        // (only display toc heading if there are more than two headings)
        [
          "remark-insert-headings",
          {
            "text": "Contents",
            "position": "start",
            "minHeadingCount": 2
          }
        ],
        ["remark-toc", { "maxDepth": 2 }]
      ]
    }
  ]
}