feat(remark): exposed "defaultRemarkPlugins" option

Author: tgreyuk

.changeset/nasty-mice-joke.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-remark': minor
+---
+
+- Exposed "defaultRemarkPlugins" option to configure which remark plugins are loaded by default (#735).

docs/pages/docs/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.3.2 (2024-12-08)
+
+### Patch Changes
+
+- Enable `{@link}` resolution on type alias properties ([#732](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/732)).
+- Remove superfluous name attribute when "useHtmlAnchors" is true..
+- Escape characters inside `@link` tags.
+- Fixed spacing around inline object declarations.
+- Always expose type arguments of reference types as per default theme ([#733](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/733)).
+
 ## 4.3.1 (2024-12-01)
 
 ### Patch Changes

docs/pages/plugins/remark/options.mdx

@@ -4,22 +4,19 @@ import { Callout } from "nextra/components";
 
 ## --remarkPlugins
 
-<Callout emoji="💡">An array of remark plugin names.</Callout>
+<Callout emoji="💡">An array of remark plugin names to be executed.</Callout>
 
 > Accepts an Array.
 
-You can provide any compatible [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) or you can write your own and reference locally.
+You can include any compatible [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) or create and reference your own locally.
 
-Each required plugin should be individually installed.
+Each plugin you wish to use must be installed individually.
 
-Options can be passed either as an array of strings or an array of string / options.
-
-Please note that `remark-frontmatter`, `remark-gfm`, and `remark-mdx` are always included by default.
+Options can be provided as either an array of strings or an array of strings with associated options.
 
 ```json filename="typedoc.json"
 {
   "remarkPlugins": [
-    "unified-prettier",
     "remark-github",
     [
       "remark-toc",
@@ -31,13 +28,38 @@ Please note that `remark-frontmatter`, `remark-gfm`, and `remark-mdx` are always
 }
 ```
 
+## --defaultRemarkPlugins
+
+<Callout emoji="💡">
+  A set of flags that control the enabling or disabling of remark plugins that
+  are loaded by default.
+</Callout>
+
+>
+
+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.
+
+However, these plugins modify the default parsing behavior of remark, which may not be ideal for all scenarios.
+
+If you'd like to disable any of these default plugins, simply set the corresponding flag to `false`.
+
+```json filename="typedoc.json"
+{
+  "defaultRemarkPlugins": {
+    "gfm": true,
+    "frontmatter": true,
+    "mdx": true
+  }
+}
+```
+
 ## --remarkStringifyOptions
 
 <Callout emoji="💡">Custom options for the remark-stringify plugin.</Callout>
 
 > Accepts a key/value object.
 
-Under the hood, the `remark-stringify` plugin is used to serialize the markdown into final output.
+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.
 

package-lock.json

@@ -14,9 +14,8 @@
     "prepublishOnly": "npm run lint && npm run build",
     "prebuild": "rm -rf dist && prebuild-options",
     "build": "tsc",
-    "postbuild": "copyfiles --up 1 ./src/**/*.mjs ./dist/",
     "pretest": "tsx ./test/__scripts__/prepare.ts",
-    "test": "node ./lint.mdx.mjs && jest",
+    "test": "jest",
     "test:update": "npm run build && npm run test -- -u"
   },
   "repository": {
@@ -31,7 +30,7 @@
     "remark": "^15.0.1",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
-    "remark-mdx": "^3.0.1",
+    "remark-mdx": "^3.1.0",
     "to-vfile": "^8.0.0"
   },
   "peerDependencies": {

packages/typedoc-plugin-remark/lint.mdx.mjs

@@ -2,6 +2,7 @@
 import { ManuallyValidatedOption } from 'typedoc';
 declare module 'typedoc' {
   export interface TypeDocOptionMap {
+    defaultRemarkPlugins: { gfm: boolean; frontmatter: boolean; mdx: boolean };
     remarkPlugins: ManuallyValidatedOption<Partial<any>>;
     remarkStringifyOptions: ManuallyValidatedOption<Partial<any>>;
   }

packages/typedoc-plugin-remark/package.json

@@ -1,10 +1,11 @@
-import { DeclarationReflection, ReflectionKind } from 'typedoc';
+import { Application, DeclarationReflection, ReflectionKind } from 'typedoc';
+import { RemarkPlugin } from '../types/remark-plugin.js';
 
 export function addTableOfContents(
   event: any,
-  remarkPlugins: any[],
+  remarkPlugins: RemarkPlugin[],
   remarkPluginsNames: string[],
-  app: any,
+  app: Application,
 ) {
   const tocPluginIndex = remarkPluginsNames.findIndex(
     (name) => name === 'remark-toc',

packages/typedoc-plugin-remark/src/_typedoc.d.ts

@@ -0,0 +1,67 @@
+import { getDefaultPlugins } from './get-default-plugins';
+
+describe('getDefaultPlugins', () => {
+  it('should return an empty array when all flags are false', () => {
+    const defaultPluginsFlag = {
+      gfm: false,
+      frontmatter: false,
+      mdx: false,
+    };
+
+    const result = getDefaultPlugins(defaultPluginsFlag);
+
+    expect(result).toEqual([]);
+  });
+
+  it('should include remark-frontmatter when frontmatter flag is true', () => {
+    const defaultPluginsFlag = {
+      gfm: false,
+      frontmatter: true,
+      mdx: false,
+    };
+
+    const result = getDefaultPlugins(defaultPluginsFlag);
+
+    expect(result).toEqual([['remark-frontmatter', ['yaml']]]);
+  });
+
+  it('should include remark-gfm when gfm flag is true', () => {
+    const defaultPluginsFlag = {
+      gfm: true,
+      frontmatter: false,
+      mdx: false,
+    };
+
+    const result = getDefaultPlugins(defaultPluginsFlag);
+
+    expect(result).toEqual(['remark-gfm']);
+  });
+
+  it('should include remark-mdx when mdx flag is true', () => {
+    const defaultPluginsFlag = {
+      gfm: false,
+      frontmatter: false,
+      mdx: true,
+    };
+
+    const result = getDefaultPlugins(defaultPluginsFlag);
+
+    expect(result).toEqual(['remark-mdx']);
+  });
+
+  it('should include all plugins when all flags are true', () => {
+    const defaultPluginsFlag = {
+      gfm: true,
+      frontmatter: true,
+      mdx: true,
+    };
+
+    const result = getDefaultPlugins(defaultPluginsFlag);
+
+    expect(result).toEqual([
+      ['remark-frontmatter', ['yaml']],
+      'remark-gfm',
+      'remark-mdx',
+    ]);
+  });
+});

packages/typedoc-plugin-remark/src/options/helpers.ts renamed to packages/typedoc-plugin-remark/src/helpers/add-toc.ts

@@ -0,0 +1,23 @@
+import { RemarkPlugin } from '../types/remark-plugin.js';
+
+export function getDefaultPlugins(defaultPluginsFlag: {
+  gfm: boolean;
+  frontmatter: boolean;
+  mdx: boolean;
+}) {
+  const defaultPlugins: RemarkPlugin[] = [];
+
+  if (defaultPluginsFlag.frontmatter) {
+    defaultPlugins.push(['remark-frontmatter', ['yaml']]);
+  }
+
+  if (defaultPluginsFlag.gfm) {
+    defaultPlugins.push('remark-gfm');
+  }
+
+  if (defaultPluginsFlag.mdx) {
+    defaultPlugins.push('remark-mdx');
+  }
+
+  return defaultPlugins;
+}

packages/typedoc-plugin-remark/src/helpers/get-default-plugins.spec.ts

@@ -6,9 +6,10 @@
 
 import { Application, DeclarationOption, RendererEvent } from 'typedoc';
 import { MarkdownPageEvent } from 'typedoc-plugin-markdown';
+import { addTableOfContents } from './helpers/add-toc.js';
+import { getDefaultPlugins } from './helpers/get-default-plugins.js';
 import * as options from './options/declarations.js';
-import { addTableOfContents } from './options/helpers.js';
-import { parseContents } from './remark.js';
+import { parse } from './parse.js';
 
 export function load(app: Application) {
   Object.entries(options).forEach(([name, option]) => {
@@ -30,24 +31,27 @@ export function load(app: Application) {
   });
 
   app.renderer.postRenderAsyncJobs.push(async (output: RendererEvent) => {
-    const remarkPlugins = app.options.getValue('remarkPlugins') as any;
+    const defaultPlugins = getDefaultPlugins(
+      app.options.getValue('defaultRemarkPlugins'),
+    );
+    const userPlugins = app.options.getValue('remarkPlugins') as string[];
+    const remarkStringifyOptions = app.options.getValue(
+      'remarkStringifyOptions',
+    );
     if (output.urls?.length) {
       await Promise.all(
         output.urls?.map(async (urlMapping) => {
           const filePath = `${output.outputDirectory}/${urlMapping.url}`;
-          const remarkStringifyOptions = app.options.getValue(
-            'remarkStringifyOptions',
-          );
-          return await parseContents(
+          return await parse(
             filePath,
+            [...defaultPlugins, ...userPlugins],
             remarkStringifyOptions,
-            remarkPlugins,
           );
         }),
       );
-      if (remarkPlugins.length) {
+      if (userPlugins.length) {
         app.logger.info(
-          `Output parsed using remark plugin(s) [${remarkPlugins
+          `Output parsed using remark plugin(s) [${userPlugins
             .map((plugin) => `"${Array.isArray(plugin) ? plugin[0] : plugin}"`)
             .join(', ')}]`,
         );