refactor: make MDX export a flat TOC list instead of tree (#6729)

packages/docusaurus-theme-common/src/index.ts

@@ -104,7 +104,11 @@ export {useHistoryPopHandler} from './utils/historyUtils';
 export {default as useTOCHighlight} from './utils/useTOCHighlight';
 export type {TOCHighlightConfig} from './utils/useTOCHighlight';
 
-export {useTOCFilter} from './utils/tocUtils';
+export {
+  useFilteredAndTreeifiedTOC,
+  useTreeifiedTOC,
+  type TOCTreeNode,
+} from './utils/tocUtils';
 
 export {
   ScrollControllerProvider,

packages/docusaurus-theme-common/src/utils/__tests__/tocUtils.test.ts

@@ -6,55 +6,53 @@
  */
 
 import type {TOCItem} from '@docusaurus/types';
-import {filterTOC} from '../tocUtils';
+import {renderHook} from '@testing-library/react-hooks';
+import {useFilteredAndTreeifiedTOC} from '../tocUtils';
 
-describe('filterTOC', () => {
+describe('useFilteredAndTreeifiedTOC', () => {
   test('filter a toc with all heading levels', () => {
     const toc: TOCItem[] = [
       {
         id: 'alpha',
         level: 1,
         value: 'alpha',
-        children: [
-          {
-            id: 'bravo',
-            level: 2,
-            value: 'Bravo',
-            children: [
-              {
-                id: 'charlie',
-                level: 3,
-                value: 'Charlie',
-                children: [
-                  {
-                    id: 'delta',
-                    level: 4,
-                    value: 'Delta',
-                    children: [
-                      {
-                        id: 'echo',
-                        level: 5,
-                        value: 'Echo',
-                        children: [
-                          {
-                            id: 'foxtrot',
-                            level: 6,
-                            value: 'Foxtrot',
-                            children: [],
-                          },
-                        ],
-                      },
-                    ],
-                  },
-                ],
-              },
-            ],
-          },
-        ],
+      },
+      {
+        id: 'bravo',
+        level: 2,
+        value: 'Bravo',
+      },
+      {
+        id: 'charlie',
+        level: 3,
+        value: 'Charlie',
+      },
+      {
+        id: 'delta',
+        level: 4,
+        value: 'Delta',
+      },
+      {
+        id: 'echo',
+        level: 5,
+        value: 'Echo',
+      },
+      {
+        id: 'foxtrot',
+        level: 6,
+        value: 'Foxtrot',
       },
     ];
 
-    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 2})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 2,
+          maxHeadingLevel: 2,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'bravo',
         level: 2,
@@ -63,7 +61,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 3, maxHeadingLevel: 3})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 3,
+          maxHeadingLevel: 3,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'charlie',
         level: 3,
@@ -72,7 +78,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 3})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 2,
+          maxHeadingLevel: 3,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'bravo',
         level: 2,
@@ -88,7 +102,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 4})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 2,
+          maxHeadingLevel: 4,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'bravo',
         level: 2,
@@ -121,24 +143,28 @@ describe('filterTOC', () => {
         id: 'charlie',
         level: 3,
         value: 'Charlie',
-        children: [],
       },
       {
         id: 'bravo',
         level: 2,
         value: 'Bravo',
-        children: [
-          {
-            id: 'delta',
-            level: 4,
-            value: 'Delta',
-            children: [],
-          },
-        ],
+      },
+      {
+        id: 'delta',
+        level: 4,
+        value: 'Delta',
       },
     ];
 
-    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 2})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 2,
+          maxHeadingLevel: 2,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'bravo',
         level: 2,
@@ -147,7 +173,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 3, maxHeadingLevel: 3})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 3,
+          maxHeadingLevel: 3,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'charlie',
         level: 3,
@@ -156,7 +190,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 4, maxHeadingLevel: 4})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 4,
+          maxHeadingLevel: 4,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'delta',
         level: 4,
@@ -165,7 +207,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 2, maxHeadingLevel: 3})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 2,
+          maxHeadingLevel: 3,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'charlie',
         level: 3,
@@ -180,7 +230,15 @@ describe('filterTOC', () => {
       },
     ]);
 
-    expect(filterTOC({toc, minHeadingLevel: 3, maxHeadingLevel: 4})).toEqual([
+    expect(
+      renderHook(() =>
+        useFilteredAndTreeifiedTOC({
+          toc,
+          minHeadingLevel: 3,
+          maxHeadingLevel: 4,
+        }),
+      ).result.current,
+    ).toEqual([
       {
         id: 'charlie',
         level: 3,

packages/docusaurus-theme-common/src/utils/tocUtils.ts

@@ -8,18 +8,64 @@
 import {useMemo} from 'react';
 import type {TOCItem} from '@docusaurus/types';
 
-type FilterTOCParam = {
-  toc: readonly TOCItem[];
-  minHeadingLevel: number;
-  maxHeadingLevel: number;
+export type TOCTreeNode = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+  readonly children: readonly TOCTreeNode[];
 };
 
-export function filterTOC({
+function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
+  const headings = flatTOC.map((heading) => ({
+    ...heading,
+    parentIndex: -1,
+    children: [] as TOCTreeNode[],
+  }));
+
+  // Keep track of which previous index would be the current heading's direct
+  // 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 rootNodes: TOCTreeNode[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading) => {
+    const {parentIndex, ...rest} = heading;
+    if (parentIndex >= 0) {
+      headings[parentIndex].children.push(rest);
+    } else {
+      rootNodes.push(rest);
+    }
+  });
+  return rootNodes;
+}
+
+export function useTreeifiedTOC(toc: TOCItem[]): readonly TOCTreeNode[] {
+  return useMemo(() => treeifyTOC(toc), [toc]);
+}
+
+function filterTOC({
   toc,
   minHeadingLevel,
   maxHeadingLevel,
-}: FilterTOCParam): TOCItem[] {
-  function isValid(item: TOCItem) {
+}: {
+  toc: readonly TOCTreeNode[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): TOCTreeNode[] {
+  function isValid(item: TOCTreeNode) {
     return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
   }
 
@@ -41,14 +87,22 @@ export function filterTOC({
   });
 }
 
-// Memoize potentially expensive filtering logic
-export function useTOCFilter({
+export function useFilteredAndTreeifiedTOC({
   toc,
   minHeadingLevel,
   maxHeadingLevel,
-}: FilterTOCParam): readonly TOCItem[] {
+}: {
+  toc: readonly TOCItem[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): readonly TOCTreeNode[] {
   return useMemo(
-    () => filterTOC({toc, minHeadingLevel, maxHeadingLevel}),
+    () =>
+      // Note: we have to filter the TOC after it has been treeified. This is
+      // mostly to ensure that weird TOC structures preserve their semantics.
+      // For example, an h3-h2-h4 sequence should not be treeified as an h3 > h4
+      // hierarchy with min=3, max=4, but should rather be [h3, h4]
+      filterTOC({toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel}),
     [toc, minHeadingLevel, maxHeadingLevel],
   );
 }