feat(remark): remark restructure and improvements

Author: tgreyuk

.changeset/config.json

@@ -13,7 +13,6 @@
   "ignore": [
     "@devtools/*",
     "typedoc-plugin-frontmatter",
-    "typedoc-plugin-remark",
     "typedoc-github-wiki-theme",
     "typedoc-gitlab-wiki-theme",
     "typedoc-vitepress-theme"

.changeset/fast-cases-film.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-remark': minor
+---
+
+- Added support for conditional "remarkPlugins" configuration.

.changeset/three-rats-rule.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-remark': major
+---
+
+- Removed "defaultRemarkPlugins" option - remark plugins are no longer added by default.

devtools/packages/prebuild-options/tasks/generate-models.ts

@@ -132,7 +132,12 @@ ${name}?: ${getType(name, option, true)};`,
     ${
       // this is a hack need to fix properly
       name === 'remarkPlugins'
-        ? 'export type RemarkPlugin = string | [string, Record<string, any>];'
+        ? `export type RemarkPlugin =
+  | [string, Record<string, any>]
+  | {
+      applyTo: string[];
+      plugins: [string, Record<string, any>][];
+    };`
         : `export interface ${capitalize(name)} {
       ${Object.entries(option.defaultValue as any)
         .map(

docs/app/layout.tsx

@@ -1,6 +1,5 @@
 import { faMarkdown } from '@fortawesome/free-brands-svg-icons';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
-
 import { Footer, Layout, Navbar } from 'nextra-theme-docs';
 import 'nextra-theme-docs/style.css';
 import { Head } from 'nextra/components';

docs/content/docs/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 4.6.2 (2025-04-09)
+
+### Patch Changes
+
+- Expose full declaration for returned union types ([#799](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/799)).
+- Move isOptional flag inside backTicks ([#797](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/797)) - thanks @LekoArts.
+- Added support for TypeDoc's v0.28.2 features `@group none`, `@category none` and `@disableGroups`.
+
+## 4.6.1 (2025-04-02)
+
+### Patch Changes
+
+- Correctly render html table when interfacePropertiesFormat=htmlTable ([#794](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/794)).
+- Correctly handle overloaded function display in list and table views ([#793](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/793)).
+- Expose comments and signatures to index signature members.
+- Wrap default values in back ticks on table views to be consistent with list views.
+- Append semi colons to signature in code blocks.
+
 ## 4.6.0 (2025-03-23)
 
 This release continues the effort to further align to TypeDoc’s default theme, with improvements that make the plugin more consistent and predictable.
@@ -57,7 +75,7 @@ From a consumer perspective there should be no direct breaking change from the p
 
 - As per TypeDoc model updates, Object literal Type Alias members are now rendered in groups ("Properties", "Methods") etc rather than under a single "Type Declaration" heading.
 - A new option "`typeAliasPropertiesFormat`" has been exposed to place properties rendered from the updated structure to a table format.
-- Type parameter list views have been updated to separate items with markdown headings for consistency and to improve readability when parameters have detailed explanations or complex properties. If type parameters are straightforward and few in number switching to `typeParametersFormat=table` might be preferable.
+- Type parameter list views have been updated to separate items with markdown headings for consistency and to improve readability when parameters have detailed explanations or complex properties. If type parameters are straightforward and few in number switching to `parametersFormat=table` might be preferable.
 
 ### Minor Changes
 

docs/content/plugins/index.mdx

@@ -1,7 +1,8 @@
-import { Cards } from 'nextra/components';
-import Image from 'next/image';
-import { faFileLines, faBook } from '@fortawesome/free-solid-svg-icons';
+{/* prettier-ignore */}
+import { faBook, faFileLines } from '@fortawesome/free-solid-svg-icons';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import Image from 'next/image';
+import { Cards } from 'nextra/components';
 
 # Utils & Themes
 
@@ -14,13 +15,22 @@ Utility plugins that can be used to provide metadata or adjust the output of the
 <Cards num={2}>
   <Cards.Card
     title="typedoc-plugin-frontmatter"
-    icon={<FontAwesomeIcon icon={faBook} />}
+    icon={
+      <Image
+        src="/logos/yaml-logo.png"
+        alt="YAML Frontmatter"
+        width={18}
+        height={18}
+      />
+    }
     arrow={true}
     href="plugins/frontmatter"
   />
   <Cards.Card
     title="typedoc-plugin-remark"
-    icon={<FontAwesomeIcon icon={faFileLines} />}
+    icon={
+      <Image src="/logos/remark-logo.png" alt="Remark" width={26} height={26} />
+    }
     arrow={true}
     href="plugins/remark"
   />

docs/content/plugins/remark/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.0.0
+
+This release includes fundamental architectural improvements and support for loading plugins conditionally based on page kind.
+
+### Architectural Changes
+
+- The plugin now constructs virtual files directly from TypeDoc's output before writing to disk rather than re-reading the corresponding file from the filesystem. This change improves performance and reliability by eliminating unnecessary disk I/O.
+- `remark-gfm`, `remark-frontmatter` and `remark-mdx` are no longer loaded by default.
+  - `remark-frontmatter` is only loaded if a frontmatter YAML block is observed in the input document.
+  - `remark-mdx` will need to be manually added if targetting MDX.
+  - `remark-gfm` will need to be manually added if other plugins require it.
+- The plugin no longer adds a placeholder heading when `remark-toc` is added. Instead this logic has been decoupled in favour of the external plugin `remark-insert-headings`.
+
 ## 1.3.0 (2025-03-16)
 
 ### Minor Changes

docs/content/plugins/remark/_meta.js

@@ -1,5 +1,7 @@
 export default {
   'quick-start': '',
   options: '',
-  'useful-plugins': '',
+  'remark-plugins-usage': '',
+  'writing-a-plugin': '',
+  CHANGELOG: '',
 };

docs/content/plugins/remark/options.mdx

@@ -12,46 +12,55 @@ You can include any compatible [remark plugins](https://github.com/remarkjs/rema
 
 Each plugin you wish to use must be installed individually.
 
-Options can be provided as either an array of strings or an array of strings with associated options.
+You can apply plugins globally to all pages, or selectively to specific kinds of pages.
 
-```json filename="typedoc.json"
+_Note: If a YAML frontmatter block is detected in the markdown, the [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter) plugin will be automatically applied to parse it._
+
+**Basic Usage (Global Plugins)**
+
+To apply Remark plugins to all documentation pages:
+
+Each item can be:
+
+- A plugin name (string)
+- A tuple of [plugin, pluginOptions]
+
+```json
 {
   "remarkPlugins": [
-    "remark-github",
-    [
-      "remark-toc",
-      {
-        "maxDepth": 3
-      }
-    ]
+    "remark-mdx",
+    ["remark-github", { "repository": "myorg/myrepo" }]
   ]
 }
 ```
 
-## defaultRemarkPlugins
+**Conditional Usage (Selective by Page Type)**
 
-<Callout emoji="💡">
-  A set of flags that control the enabling or disabling of remark plugins that
-  are loaded by default.
-</Callout>
+To apply plugins only to specific page kinds, use grouped objects:
 
->
+```json
+{
+  "remarkPlugins": [
+    {
+      "applyTo": "*",
+      "plugins": ["remark-mdx"]
+    },
+    {
+      "applyTo": ["Class", "Interface"],
+      "plugins": ["remark-github", { "repository": "myorg/myrepo" }]
+    }
+  ]
+}
+```
 
-By default, the plugins [`remark-gfm`](https://github.com/remarkjs/remark-gfm), [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter), and [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx) are included, as these are considered the most common use cases.
+**Supported applyTo Values**
 
-However, these plugins modify the default parsing behavior of remark, which may not be ideal for all scenarios.
+You can target specific pages using the `applyTo` field.
 
-If you'd like to disable any of these default plugins, simply set the corresponding flag to `false`.
+The following applyTo values are supported:
 
-```json filename="typedoc.json"
-{
-  "defaultRemarkPlugins": {
-    "gfm": true,
-    "frontmatter": true,
-    "mdx": true
-  }
-}
-```
+- `"*"` applies to all pages
+- An array of on or more of the following page kinds: [`"Readme"`, `"Index"`, `"Module"`, `"Namespace"`, `"Document"`, `"Class"`, `"Interface"`, `"Enum"`, `"TypeAlias"`, `"Function"`, `"Variable"`].
 
 ## remarkStringifyOptions
 
@@ -61,9 +70,7 @@ If you'd like to disable any of these default plugins, simply set the correspond
 
 Under the hood, the [`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify) plugin is used to serialize the markdown into final output.
 
-You can pass in options to the `remark-stringify` plugin using this option.
-
-Please see https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options
+Please see https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options for available options to pass to the plugin.
 
 ```json filename="typedoc.json"
 {

docs/content/plugins/remark/remark-plugins-usage.mdx

@@ -0,0 +1,97 @@
+# 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](https://github.com/remarkjs/remark/blob/main/doc/plugins.md)
+
+### remark-mdx
+
+https://mdxjs.com/packages/remark-mdx
+
+- If you are using MDX, this plugin is required to correctly parse to MDX.
+
+```sh npm2yarn
+npm install remark-mdx --save-dev
+```
+
+```json filename="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.
+
+```sh npm2yarn
+npm install remark-github --save-dev
+```
+
+```json filename="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`](https://github.com/tgreyuk/remark-insert-headings) to add insert placeholder heading._
+
+```sh npm2yarn
+npm install remark-insert-headings remark-toc --save-dev
+```
+
+```json filename="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._
+
+```json filename="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 }]
+      ]
+    }
+  ]
+}
+```

docs/content/plugins/remark/useful-plugins.mdx

@@ -0,0 +1,23 @@
+# Writing A Plugin
+
+It is straightforward to create a remark plugin locally if you would like to create your own functionality.
+
+This example shows how to create a very simple plugin that adds a `meta` property to all code blocks in the documentation.
+
+```js filename="my-custom-plugin.mjs"
+import { visit } from 'unist-util-visit';
+
+export default function mySimpleRemarkPlugin() {
+  return (tree) => {
+    visit(tree, 'code', (node) => {
+      node.meta = `playground`;
+    });
+  };
+}
+```
+
+```json filename="typedoc.json"
+{
+  "remarkPlugins": ["./my-custom-plugin.mjs"]
+}
+```