feat(v2): allow specifying TOC max depth (themeConfig + frontMatter)

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__snapshots__/index.test.ts.snap

@@ -9,24 +9,29 @@ exports[`inline code should be escaped 1`] = `
 			{
 				value: '<code>&lt;Head&gt;Test&lt;/Head&gt;</code>',
 				id: 'headtesthead',
-				children: []
+				children: [],
+				level: 3
 			}
-		]
+		],
+		level: 2
 	},
 	{
 		value: '<code>&lt;div /&gt;</code>',
 		id: 'div-',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<code>&lt;div&gt; Test &lt;/div&gt;</code>',
 		id: 'div-test-div',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>',
 		id: 'divitestidiv',
-		children: []
+		children: [],
+		level: 2
 	}
 ];
 
@@ -51,24 +56,29 @@ exports[`non text phrasing content 1`] = `
 			{
 				value: '<strong>Importance</strong>',
 				id: 'importance',
-				children: []
+				children: [],
+				level: 3
 			}
-		]
+		],
+		level: 2
 	},
 	{
 		value: '<del>Strikethrough</del>',
 		id: 'strikethrough',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<i>HTML</i>',
 		id: 'html',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<code>inline.code()</code>',
 		id: 'inlinecode',
-		children: []
+		children: [],
+		level: 2
 	}
 ];
 
@@ -83,3 +93,55 @@ exports[`non text phrasing content 1`] = `
 ## \`inline.code()\`
 "
 `;
+
+exports[`should process all heading levels 1`] = `
+"export const toc = [
+	{
+		value: 'Bravo',
+		id: 'bravo',
+		children: [
+			{
+				value: 'Charlie',
+				id: 'charlie',
+				children: [
+					{
+						value: 'Delta',
+						id: 'delta',
+						children: [
+							{
+								value: 'Echo',
+								id: 'echo',
+								children: [
+									{
+										value: 'Foxtrot',
+										id: 'foxtrot',
+										children: [],
+										level: 6
+									}
+								],
+								level: 5
+							}
+						],
+						level: 4
+					}
+				],
+				level: 3
+			}
+		],
+		level: 2
+	}
+];
+
+# Alpha
+
+## Bravo
+
+### Charlie
+
+#### Delta
+
+##### Echo
+
+###### Foxtrot
+"
+`;

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/maximum-depth-6.md

@@ -0,0 +1,11 @@
+# Alpha
+
+## Bravo
+
+### Charlie
+
+#### Delta
+
+##### Echo
+
+###### Foxtrot

packages/docusaurus-mdx-loader/src/remark/toc/__tests__/index.test.ts

@@ -12,7 +12,7 @@ import vfile from 'to-vfile';
 import plugin from '../index';
 import headings from '../../headings/index';
 
-const processFixture = async (name, options) => {
+const processFixture = async (name, options?) => {
   const path = join(__dirname, 'fixtures', `${name}.md`);
   const file = await vfile.read(path);
   const result = await remark()
@@ -41,7 +41,8 @@ test('text content', async () => {
     	{
     		value: 'Endi',
     		id: 'endi',
-    		children: []
+    		children: [],
+    		level: 3
     	},
     	{
     		value: 'Endi',
@@ -50,14 +51,17 @@ test('text content', async () => {
     			{
     				value: 'Yangshun',
     				id: 'yangshun',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	},
     	{
     		value: 'I ♥ unicode.',
     		id: 'i--unicode',
-    		children: []
+    		children: [],
+    		level: 2
     	}
     ];
 
@@ -87,7 +91,8 @@ test('should export even with existing name', async () => {
     	{
     		value: 'Thanos',
     		id: 'thanos',
-    		children: []
+    		children: [],
+    		level: 2
     	},
     	{
     		value: 'Tony Stark',
@@ -96,9 +101,11 @@ test('should export even with existing name', async () => {
     			{
     				value: 'Avengers',
     				id: 'avengers',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	}
     ];
 
@@ -121,7 +128,8 @@ test('should export with custom name', async () => {
     	{
     		value: 'Endi',
     		id: 'endi',
-    		children: []
+    		children: [],
+    		level: 3
     	},
     	{
     		value: 'Endi',
@@ -130,14 +138,17 @@ test('should export with custom name', async () => {
     			{
     				value: 'Yangshun',
     				id: 'yangshun',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	},
     	{
     		value: 'I ♥ unicode.',
     		id: 'i--unicode',
-    		children: []
+    		children: [],
+    		level: 2
     	}
     ];
 
@@ -171,7 +182,8 @@ test('should insert below imports', async () => {
     	{
     		value: 'Title',
     		id: 'title',
-    		children: []
+    		children: [],
+    		level: 2
     	},
     	{
     		value: 'Test',
@@ -180,9 +192,11 @@ test('should insert below imports', async () => {
     			{
     				value: 'Again',
     				id: 'again',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	}
     ];
 
@@ -210,3 +224,8 @@ test('empty headings', async () => {
     "
   `);
 });
+
+test('should process all heading levels', async () => {
+  const result = await processFixture('maximum-depth-6');
+  expect(result).toMatchSnapshot();
+});

packages/docusaurus-mdx-loader/src/remark/toc/search.ts

@@ -8,40 +8,75 @@
 import toString from 'mdast-util-to-string';
 import visit, {Visitor} from 'unist-util-visit';
 import {toValue} from '../utils';
-import type {TOCItem as TOC} from '@docusaurus/types';
+import type {TOCItem} from '@docusaurus/types';
 import type {Node} from 'unist';
 import type {Heading} from 'mdast';
 
-// Visit all headings. We `slug` all headings (to account for
-// duplicates), but only take h2 and h3 headings.
-export default function search(node: Node): TOC[] {
-  const headings: TOC[] = [];
-  let current = -1;
-  let currentDepth = 0;
+// Intermediate interface for TOC algorithm
+interface SearchItem {
+  node: TOCItem;
+  level: number;
+  parentIndex: number;
+}
+
+/**
+ *
+ * Generate a TOC AST from the raw Markdown contents
+ */
+export default function search(node: Node): TOCItem[] {
+  const headings: SearchItem[] = [];
 
   const visitor: Visitor<Heading> = (child, _index, parent) => {
     const value = toString(child);
 
-    if (parent !== node || !value || child.depth > 3 || child.depth < 2) {
+    // depth:1 headings are titles and not included in the TOC
+    if (parent !== node || !value || child.depth < 2) {
       return;
     }
 
-    const entry: TOC = {
-      value: toValue(child),
-      id: child.data!.id as string,
-      children: [],
-    };
-
-    if (!headings.length || currentDepth >= child.depth) {
-      headings.push(entry);
-      current += 1;
-      currentDepth = child.depth;
-    } else {
-      headings[current].children.push(entry);
-    }
+    headings.push({
+      node: {
+        value: toValue(child),
+        id: child.data!.id as string,
+        children: [],
+        level: child.depth,
+      },
+      level: child.depth,
+      parentIndex: -1,
+    });
   };
 
   visit(node, 'heading', visitor);
 
-  return headings;
+  // Keep track of which previous index would be the current heading's direcy parent.
+  // Each entry <i> is the last index of the `headings` array at heading level <i>.
+  // We will modify these indices as we iterate through all headings.
+  // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2
+  // indices 0 and 1 will remain unused.
+  const prevIndexForLevel = Array(7).fill(-1);
+
+  headings.forEach((curr, currIndex) => {
+    // take the last seen index for each ancestor level. the highest
+    // index will be the direct ancestor of the current heading.
+    const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+    curr.parentIndex = Math.max(...ancestorLevelIndexes);
+    // mark that curr.level was last seen at the current index
+    prevIndexForLevel[curr.level] = currIndex;
+  });
+
+  const rootNodeIndexes: number[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading, i) => {
+    if (heading.parentIndex >= 0) {
+      headings[heading.parentIndex].node.children.push(heading.node);
+    } else {
+      rootNodeIndexes.push(i);
+    }
+  });
+
+  const toc = headings
+    .filter((_, k) => rootNodeIndexes.includes(k)) // only return root nodes
+    .map((heading) => heading.node); // only return Node, no metadata
+  return toc;
 }

packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts

@@ -65,6 +65,8 @@ export type BlogPostFrontMatter = {
   image?: string;
   keywords?: string[];
   hide_table_of_contents?: boolean;
+  toc_max_heading_level?: number;
+  toc_min_heading_level?: number;
   /* eslint-enable camelcase */
 };
 

packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts

@@ -32,6 +32,12 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  toc_max_heading_level: Joi.number().min(2).max(6),
+  toc_min_heading_level: Joi.number().when('toc_max_heading_level', {
+    is: Joi.exist(),
+    then: Joi.number().min(2).max(Joi.ref('toc_max_heading_level')),
+    otherwise: Joi.number().min(2).max(6),
+  }),
 }).unknown();
 
 export function validateDocFrontMatter(

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -94,6 +94,8 @@ declare module '@theme/DocItem' {
     /* eslint-disable camelcase */
     readonly hide_title?: boolean;
     readonly hide_table_of_contents?: boolean;
+    readonly toc_max_heading_level?: number;
+    readonly toc_min_heading_level?: number;
     /* eslint-enable camelcase */
   };