fix(remark): remove heading count restriction when adding toc placeholder

Author: tgreyuk

.changeset/cold-yaks-know.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-remark': patch
+---
+
+- Remove heading count restriction when adding toc placeholder heading (for usage with remark-toc).

docs/pages/docs/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 4.3.3 (2024-12-18)
+
+### Patch Changes
+
+- Correctly handle anchor resolutions with table formats.
+- Fix invalid typescript syntax for type aliases inside declaration code blocks when "useCodeBlocks" is true ([#741](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/741)).
+
 ## 4.3.2 (2024-12-08)
 
 ### Patch Changes

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

@@ -8,6 +8,9 @@ https://github.com/remarkjs/remark-toc
 
 - Adds inline table of contents to pages.
 
+Note: This plugin searches for a heading in the page to generate the table of contents.
+`typedoc-plugin-remark` inserts this heading automatically (currently to Module, Interface, Class and Enum pages).
+
 ```sh npm2yarn
 npm install remark-toc --save-dev
 ```

packages/typedoc-plugin-remark/src/index.ts

@@ -43,13 +43,15 @@ export function load(app: Application) {
               (name) => name === 'remark-toc',
             );
             const tocPlugin = remarkPlugins[tocPluginIndex];
-            const tocOptions = Array.isArray(tocPlugin) ? tocPlugin[1] : {};
+            const remarkTocOptions = Array.isArray(tocPlugin)
+              ? tocPlugin[1]
+              : {};
             defaultPlugins.push([
               path.join(__dirname, 'plugins', 'add-toc.js'),
               {
                 reflection: urlMapping.model,
                 typedocOptions: app.options,
-                tocOptions,
+                remarkTocOptions,
               },
             ]);
           }

packages/typedoc-plugin-remark/src/plugins/add-toc.ts

@@ -4,14 +4,17 @@ import { Node } from 'unist';
 import { visit } from 'unist-util-visit';
 
 /**
- * This plugin is used internally to add a toc heading as required to be present in the page when using the remark-toc plugin.
+ * This plugin internally adds a TOC heading to document as required by remark-toc.
  */
-export default function (options: any) {
-  const { reflection, typedocOptions, tocOptions } = options;
+export default function (options: {
+  reflection: DeclarationReflection;
+  typedocOptions: Options;
+  remarkTocOptions: { heading: string };
+}) {
+  const { reflection, typedocOptions, remarkTocOptions } = options;
 
   return (tree: Node) => {
-    // If the current page is already an index page, do nothing.
-    if (isIndexPage(reflection, typedocOptions)) {
+    if (!shouldAddToc(reflection, typedocOptions)) {
       return tree;
     }
     visit(
@@ -25,7 +28,7 @@ export default function (options: any) {
             children: [
               {
                 type: 'text',
-                value: tocOptions?.heading || 'Contents',
+                value: remarkTocOptions?.heading || 'Contents',
               },
             ],
           };
@@ -39,24 +42,37 @@ export default function (options: any) {
 
 /**
  * Determine if the current page is already an index page.
- * - Reflection is a project and all children are modules.
- * - Reflection is a module and outputFileStrategy is equal to "members".
+ *
+ * Returns false if
+ *
+ * - The reflection is a module or project and outputFileStrategy is equal to "members".
+ * - The reflection is a project and all children are modules.
+ * - The reflection kind is not in the list of allowed kinds.
+ * -
  */
-function isIndexPage(
+function shouldAddToc(
   reflection: DeclarationReflection,
   typedocOptions: Options,
 ) {
   if (
-    reflection.kind === ReflectionKind.Project &&
-    reflection.children?.every((child) => child.kind === ReflectionKind.Module)
+    [ReflectionKind.Project, ReflectionKind.Module].includes(reflection.kind) &&
+    typedocOptions?.getValue('outputFileStrategy') === 'members'
   ) {
-    return true;
+    return false;
   }
   if (
-    [ReflectionKind.Project, ReflectionKind.Module].includes(reflection.kind) &&
-    typedocOptions?.getValue('outputFileStrategy') === 'members'
+    reflection.kind === ReflectionKind.Project &&
+    reflection.children?.every((child) => child.kind === ReflectionKind.Module)
   ) {
-    return true;
+    return false;
   }
-  return false;
+  return [
+    ReflectionKind.Project,
+    ReflectionKind.Module,
+    ReflectionKind.Namespace,
+    ReflectionKind.Class,
+    ReflectionKind.Enum,
+    ReflectionKind.Interface,
+    ReflectionKind.Document,
+  ].includes(reflection.kind);
 }

packages/typedoc-plugin-remark/test/typedoc.toc.json

@@ -3,5 +3,7 @@
   "tsconfig": "./stubs/tsconfig.json",
   "plugin": ["typedoc-plugin-markdown", "typedoc-plugin-remark"],
   "remarkPlugins": [["remark-toc", { "maxDepth": 3 }]],
-  "readme": "none"
+  "readme": "none",
+  "disableSources": true,
+  "hidePageHeader": true
 }