mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 15:47:23 +02:00
refactor: make MDX export a flat TOC list instead of tree (#6729)
This commit is contained in:
parent
2d93750caf
commit
c3370be64d
20 changed files with 312 additions and 445 deletions
|
@ -5,32 +5,26 @@ exports[`inline code should be escaped 1`] = `
|
|||
{
|
||||
value: '<code><Head /></code>',
|
||||
id: 'head-',
|
||||
children: [
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<code><Head>Test</Head></code>',
|
||||
id: 'headtesthead',
|
||||
children: [],
|
||||
level: 3
|
||||
}
|
||||
],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<code><div /></code>',
|
||||
id: 'div-',
|
||||
children: [],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<code><div> Test </div></code>',
|
||||
id: 'div-test-div',
|
||||
children: [],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<code><div><i>Test</i></div></code>',
|
||||
id: 'divitestidiv',
|
||||
children: [],
|
||||
level: 2
|
||||
}
|
||||
];
|
||||
|
@ -52,32 +46,26 @@ exports[`non text phrasing content 1`] = `
|
|||
{
|
||||
value: '<em>Emphasis</em>',
|
||||
id: 'emphasis',
|
||||
children: [
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<strong>Importance</strong>',
|
||||
id: 'importance',
|
||||
children: [],
|
||||
level: 3
|
||||
}
|
||||
],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<del>Strikethrough</del>',
|
||||
id: 'strikethrough',
|
||||
children: [],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<i>HTML</i>',
|
||||
id: 'html',
|
||||
children: [],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: '<code>inline.code()</code>',
|
||||
id: 'inlinecode',
|
||||
children: [],
|
||||
level: 2
|
||||
}
|
||||
];
|
||||
|
|
|
@ -41,26 +41,21 @@ test('text content', async () => {
|
|||
{
|
||||
value: 'Endi',
|
||||
id: 'endi',
|
||||
children: [],
|
||||
level: 3
|
||||
},
|
||||
{
|
||||
value: 'Endi',
|
||||
id: 'endi-1',
|
||||
children: [
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'Yangshun',
|
||||
id: 'yangshun',
|
||||
children: [],
|
||||
level: 3
|
||||
}
|
||||
],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'I ♥ unicode.',
|
||||
id: 'i--unicode',
|
||||
children: [],
|
||||
level: 2
|
||||
}
|
||||
];
|
||||
|
@ -91,22 +86,18 @@ test('should export even with existing name', async () => {
|
|||
{
|
||||
value: 'Thanos',
|
||||
id: 'thanos',
|
||||
children: [],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'Tony Stark',
|
||||
id: 'tony-stark',
|
||||
children: [
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'Avengers',
|
||||
id: 'avengers',
|
||||
children: [],
|
||||
level: 3
|
||||
}
|
||||
],
|
||||
level: 2
|
||||
}
|
||||
];
|
||||
|
||||
## Thanos
|
||||
|
@ -128,26 +119,21 @@ test('should export with custom name', async () => {
|
|||
{
|
||||
value: 'Endi',
|
||||
id: 'endi',
|
||||
children: [],
|
||||
level: 3
|
||||
},
|
||||
{
|
||||
value: 'Endi',
|
||||
id: 'endi-1',
|
||||
children: [
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'Yangshun',
|
||||
id: 'yangshun',
|
||||
children: [],
|
||||
level: 3
|
||||
}
|
||||
],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'I ♥ unicode.',
|
||||
id: 'i--unicode',
|
||||
children: [],
|
||||
level: 2
|
||||
}
|
||||
];
|
||||
|
@ -182,22 +168,18 @@ test('should insert below imports', async () => {
|
|||
{
|
||||
value: 'Title',
|
||||
id: 'title',
|
||||
children: [],
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'Test',
|
||||
id: 'test',
|
||||
children: [
|
||||
level: 2
|
||||
},
|
||||
{
|
||||
value: 'Again',
|
||||
id: 'again',
|
||||
children: [],
|
||||
level: 3
|
||||
}
|
||||
],
|
||||
level: 2
|
||||
}
|
||||
];
|
||||
|
||||
## Title
|
||||
|
|
|
@ -1,182 +0,0 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
import remark from 'remark';
|
||||
import mdx from 'remark-mdx';
|
||||
import search from '../search';
|
||||
import headings from '../../headings/index';
|
||||
|
||||
const getHeadings = async (mdText: string) => {
|
||||
const node = remark().parse(mdText);
|
||||
const result = await remark().use(headings).use(mdx).run(node);
|
||||
return search(result);
|
||||
};
|
||||
|
||||
test('should process all heading levels', async () => {
|
||||
const md = `
|
||||
# Alpha
|
||||
|
||||
## Bravo
|
||||
|
||||
### Charlie
|
||||
|
||||
#### Delta
|
||||
|
||||
##### Echo
|
||||
|
||||
###### Foxtrot
|
||||
|
||||
`;
|
||||
|
||||
await expect(getHeadings(md)).resolves.toEqual([
|
||||
{
|
||||
children: [
|
||||
{
|
||||
children: [
|
||||
{
|
||||
children: [
|
||||
{
|
||||
children: [
|
||||
{
|
||||
children: [],
|
||||
id: 'foxtrot',
|
||||
level: 6,
|
||||
value: 'Foxtrot',
|
||||
},
|
||||
],
|
||||
id: 'echo',
|
||||
level: 5,
|
||||
value: 'Echo',
|
||||
},
|
||||
],
|
||||
id: 'delta',
|
||||
level: 4,
|
||||
value: 'Delta',
|
||||
},
|
||||
],
|
||||
id: 'charlie',
|
||||
level: 3,
|
||||
value: 'Charlie',
|
||||
},
|
||||
],
|
||||
id: 'bravo',
|
||||
level: 2,
|
||||
value: 'Bravo',
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
test('should process real-world well-formatted md', async () => {
|
||||
const md = `
|
||||
# title
|
||||
|
||||
some text
|
||||
|
||||
## section 1
|
||||
|
||||
some text
|
||||
|
||||
### subsection 1-1
|
||||
|
||||
some text
|
||||
|
||||
#### subsection 1-1-1
|
||||
|
||||
some text
|
||||
|
||||
#### subsection 1-1-2
|
||||
|
||||
some text
|
||||
|
||||
### subsection 1-2
|
||||
|
||||
some text
|
||||
|
||||
### subsection 1-3
|
||||
|
||||
some text
|
||||
|
||||
## section 2
|
||||
|
||||
some text
|
||||
|
||||
### subsection 2-1
|
||||
|
||||
some text
|
||||
|
||||
### subsection 2-1
|
||||
|
||||
some text
|
||||
|
||||
## section 3
|
||||
|
||||
some text
|
||||
|
||||
### subsection 3-1
|
||||
|
||||
some text
|
||||
|
||||
### subsection 3-2
|
||||
|
||||
some text
|
||||
|
||||
`;
|
||||
|
||||
await expect(getHeadings(md)).resolves.toEqual([
|
||||
{
|
||||
children: [
|
||||
{
|
||||
children: [
|
||||
{
|
||||
children: [],
|
||||
id: 'subsection-1-1-1',
|
||||
level: 4,
|
||||
value: 'subsection 1-1-1',
|
||||
},
|
||||
{
|
||||
children: [],
|
||||
id: 'subsection-1-1-2',
|
||||
level: 4,
|
||||
value: 'subsection 1-1-2',
|
||||
},
|
||||
],
|
||||
id: 'subsection-1-1',
|
||||
level: 3,
|
||||
value: 'subsection 1-1',
|
||||
},
|
||||
{children: [], id: 'subsection-1-2', level: 3, value: 'subsection 1-2'},
|
||||
{children: [], id: 'subsection-1-3', level: 3, value: 'subsection 1-3'},
|
||||
],
|
||||
id: 'section-1',
|
||||
level: 2,
|
||||
value: 'section 1',
|
||||
},
|
||||
{
|
||||
children: [
|
||||
{children: [], id: 'subsection-2-1', level: 3, value: 'subsection 2-1'},
|
||||
{
|
||||
children: [],
|
||||
id: 'subsection-2-1-1',
|
||||
level: 3,
|
||||
value: 'subsection 2-1',
|
||||
},
|
||||
],
|
||||
id: 'section-2',
|
||||
level: 2,
|
||||
value: 'section 2',
|
||||
},
|
||||
{
|
||||
children: [
|
||||
{children: [], id: 'subsection-3-1', level: 3, value: 'subsection 3-1'},
|
||||
{children: [], id: 'subsection-3-2', level: 3, value: 'subsection 3-2'},
|
||||
],
|
||||
id: 'section-3',
|
||||
level: 2,
|
||||
value: 'section 3',
|
||||
},
|
||||
]);
|
||||
});
|
|
@ -9,10 +9,14 @@ import {parse, type ParserOptions} from '@babel/parser';
|
|||
import type {Identifier} from '@babel/types';
|
||||
import traverse from '@babel/traverse';
|
||||
import stringifyObject from 'stringify-object';
|
||||
import search from './search';
|
||||
import type {Plugin, Transformer} from 'unified';
|
||||
import toString from 'mdast-util-to-string';
|
||||
import visit from 'unist-util-visit';
|
||||
import {toValue} from '../utils';
|
||||
|
||||
import type {TOCItem} from '@docusaurus/types';
|
||||
import type {Node, Parent} from 'unist';
|
||||
import type {Literal} from 'mdast';
|
||||
import type {Heading, Literal} from 'mdast';
|
||||
import type {Plugin, Transformer} from 'unified';
|
||||
|
||||
const parseOptions: ParserOptions = {
|
||||
plugins: ['jsx'],
|
||||
|
@ -70,7 +74,22 @@ const plugin: Plugin<[PluginOptions?]> = (options = {}) => {
|
|||
const name = options.name || 'toc';
|
||||
|
||||
const transformer: Transformer = (node) => {
|
||||
const headings = search(node);
|
||||
const headings: TOCItem[] = [];
|
||||
|
||||
visit(node, 'heading', (child: Heading, _index, parent) => {
|
||||
const value = toString(child);
|
||||
|
||||
// depth:1 headings are titles and not included in the TOC
|
||||
if (parent !== node || !value || child.depth < 2) {
|
||||
return;
|
||||
}
|
||||
|
||||
headings.push({
|
||||
value: toValue(child),
|
||||
id: child.data!.id as string,
|
||||
level: child.depth,
|
||||
});
|
||||
});
|
||||
const {children} = node as Parent<Literal>;
|
||||
const targetIndex = getOrCreateExistingTargetIndex(children, name);
|
||||
|
||||
|
|
|
@ -1,80 +0,0 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
import toString from 'mdast-util-to-string';
|
||||
import visit from 'unist-util-visit';
|
||||
import {toValue} from '../utils';
|
||||
import type {TOCItem} from '@docusaurus/types';
|
||||
import type {Node} from 'unist';
|
||||
import type {Heading} from 'mdast';
|
||||
|
||||
// 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[] = [];
|
||||
|
||||
visit(node, 'heading', (child: Heading, _index, parent) => {
|
||||
const value = toString(child);
|
||||
|
||||
// depth:1 headings are titles and not included in the TOC
|
||||
if (parent !== node || !value || child.depth < 2) {
|
||||
return;
|
||||
}
|
||||
|
||||
headings.push({
|
||||
node: {
|
||||
value: toValue(child),
|
||||
id: child.data!.id as string,
|
||||
children: [],
|
||||
level: child.depth,
|
||||
},
|
||||
level: child.depth,
|
||||
parentIndex: -1,
|
||||
});
|
||||
});
|
||||
|
||||
// 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 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;
|
||||
}
|
|
@ -7,12 +7,12 @@
|
|||
|
||||
import React, {useMemo} from 'react';
|
||||
import type {Props} from '@theme/TOCItems';
|
||||
import type {TOCItem} from '@docusaurus/types';
|
||||
import {
|
||||
type TOCHighlightConfig,
|
||||
type TOCTreeNode,
|
||||
useThemeConfig,
|
||||
useTOCFilter,
|
||||
useTOCHighlight,
|
||||
useFilteredAndTreeifiedTOC,
|
||||
} from '@docusaurus/theme-common';
|
||||
|
||||
// Recursive component rendering the toc tree
|
||||
|
@ -23,7 +23,7 @@ function TOCItemList({
|
|||
linkClassName,
|
||||
isChild,
|
||||
}: {
|
||||
readonly toc: readonly TOCItem[];
|
||||
readonly toc: readonly TOCTreeNode[];
|
||||
readonly className: string;
|
||||
readonly linkClassName: string | null;
|
||||
readonly isChild?: boolean;
|
||||
|
@ -70,7 +70,11 @@ export default function TOCItems({
|
|||
const maxHeadingLevel =
|
||||
maxHeadingLevelOption ?? themeConfig.tableOfContents.maxHeadingLevel;
|
||||
|
||||
const tocFiltered = useTOCFilter({toc, minHeadingLevel, maxHeadingLevel});
|
||||
const tocTree = useFilteredAndTreeifiedTOC({
|
||||
toc,
|
||||
minHeadingLevel,
|
||||
maxHeadingLevel,
|
||||
});
|
||||
|
||||
const tocHighlightConfig: TOCHighlightConfig | undefined = useMemo(() => {
|
||||
if (linkClassName && linkActiveClassName) {
|
||||
|
@ -87,7 +91,7 @@ export default function TOCItems({
|
|||
|
||||
return (
|
||||
<TOCItemList
|
||||
toc={tocFiltered}
|
||||
toc={tocTree}
|
||||
className={className}
|
||||
linkClassName={linkClassName}
|
||||
{...props}
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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: [],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
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: [],
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
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,
|
||||
|
|
|
@ -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],
|
||||
);
|
||||
}
|
||||
|
|
5
packages/docusaurus-types/src/index.d.ts
vendored
5
packages/docusaurus-types/src/index.d.ts
vendored
|
@ -429,12 +429,11 @@ export interface ThemeConfigValidationContext<T> {
|
|||
themeConfig: Partial<T>;
|
||||
}
|
||||
|
||||
export interface TOCItem {
|
||||
export type TOCItem = {
|
||||
readonly value: string;
|
||||
readonly id: string;
|
||||
readonly children: TOCItem[];
|
||||
readonly level: number;
|
||||
}
|
||||
};
|
||||
|
||||
export type RouteChunksTree = {[x: string | number]: string | RouteChunksTree};
|
||||
|
||||
|
|
|
@ -246,6 +246,7 @@ stylelintrc
|
|||
sublabel
|
||||
sublicensable
|
||||
sublist
|
||||
subsubsection
|
||||
subpage
|
||||
subroute
|
||||
subroutes
|
||||
|
@ -260,6 +261,7 @@ toolset
|
|||
toplevel
|
||||
transifex
|
||||
transpiles
|
||||
treeified
|
||||
treeify
|
||||
treosh
|
||||
triaging
|
||||
|
|
|
@ -25,12 +25,6 @@ Once your website is bootstrapped, the website source will contain the Docusauru
|
|||
}
|
||||
```
|
||||
|
||||
## Index {#index}
|
||||
|
||||
import TOCInline from "@theme/TOCInline"
|
||||
|
||||
<TOCInline toc={toc[1].children}/>
|
||||
|
||||
## Docusaurus CLI commands {#docusaurus-cli-commands}
|
||||
|
||||
Below is a list of Docusaurus CLI commands and their usages:
|
||||
|
|
|
@ -17,7 +17,7 @@ However, it can be helpful if you have a high-level understanding of how the con
|
|||
|
||||
The high-level overview of Docusaurus configuration can be categorized into:
|
||||
|
||||
<TOCInline toc={toc[0].children} />
|
||||
<TOCInline toc={toc} minHeadingLevel={3} maxHeadingLevel={3} />
|
||||
|
||||
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md).
|
||||
|
||||
|
|
|
@ -35,33 +35,30 @@ import TOCInline from '@theme/TOCInline';
|
|||
|
||||
## Custom table of contents {#custom-table-of-contents}
|
||||
|
||||
The `toc` props is just a list of table of contents items:
|
||||
The `toc` prop is just a list of heading items:
|
||||
|
||||
```ts
|
||||
type TOCItem = {
|
||||
value: string;
|
||||
id: string;
|
||||
children: TOCItem[];
|
||||
level: number;
|
||||
};
|
||||
```
|
||||
|
||||
You can create this TOC tree manually, or derive a new TOC tree from the `toc` variable:
|
||||
Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
|
||||
|
||||
```jsx
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
<TOCInline
|
||||
toc={
|
||||
// Only show 3th and 5th top-level heading
|
||||
[toc[2], toc[4]]
|
||||
}
|
||||
// Only show h2 and h4 headings
|
||||
toc={toc.filter((node) => node.level === 2 || node.level === 4)}
|
||||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<TOCInline toc={[toc[2], toc[4]]} />
|
||||
<TOCInline toc={toc.filter((node) => node.level === 2 || node.level === 4)} />
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
|
@ -81,14 +78,32 @@ Lorem ipsum
|
|||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 1 a I
|
||||
|
||||
#### Example subsubsection 1 a II
|
||||
|
||||
#### Example subsubsection 1 a III
|
||||
|
||||
### Example Subsection 1 b {#example-subsection-1-b}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 1 b I
|
||||
|
||||
#### Example subsubsection 1 b II
|
||||
|
||||
#### Example subsubsection 1 b III
|
||||
|
||||
### Example Subsection 1 c {#example-subsection-1-c}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 1 c I
|
||||
|
||||
#### Example subsubsection 1 c II
|
||||
|
||||
#### Example subsubsection 1 c III
|
||||
|
||||
## Example Section 2 {#example-section-2}
|
||||
|
||||
Lorem ipsum
|
||||
|
@ -97,14 +112,32 @@ Lorem ipsum
|
|||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 2 a I
|
||||
|
||||
#### Example subsubsection 2 a II
|
||||
|
||||
#### Example subsubsection 2 a III
|
||||
|
||||
### Example Subsection 2 b {#example-subsection-2-b}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 2 b I
|
||||
|
||||
#### Example subsubsection 2 b II
|
||||
|
||||
#### Example subsubsection 2 b III
|
||||
|
||||
### Example Subsection 2 c {#example-subsection-2-c}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 2 c I
|
||||
|
||||
#### Example subsubsection 2 c II
|
||||
|
||||
#### Example subsubsection 2 c III
|
||||
|
||||
## Example Section 3 {#example-section-3}
|
||||
|
||||
Lorem ipsum
|
||||
|
@ -113,10 +146,28 @@ Lorem ipsum
|
|||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 3 a I
|
||||
|
||||
#### Example subsubsection 3 a II
|
||||
|
||||
#### Example subsubsection 3 a III
|
||||
|
||||
### Example Subsection 3 b {#example-subsection-3-b}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 3 b I
|
||||
|
||||
#### Example subsubsection 3 b II
|
||||
|
||||
#### Example subsubsection 3 b III
|
||||
|
||||
### Example Subsection 3 c {#example-subsection-3-c}
|
||||
|
||||
Lorem ipsum
|
||||
|
||||
#### Example subsubsection 3 c I
|
||||
|
||||
#### Example subsubsection 3 c II
|
||||
|
||||
#### Example subsubsection 3 c III
|
||||
|
|
|
@ -25,12 +25,6 @@ Once your website is bootstrapped, the website source will contain the Docusauru
|
|||
}
|
||||
```
|
||||
|
||||
## Index {#index}
|
||||
|
||||
import TOCInline from "@theme/TOCInline"
|
||||
|
||||
<TOCInline toc={toc[1].children}/>
|
||||
|
||||
## Docusaurus CLI commands {#docusaurus-cli-commands}
|
||||
|
||||
Below is a list of Docusaurus CLI commands and their usages:
|
||||
|
|
|
@ -17,7 +17,7 @@ However, it can be helpful if you have a high-level understanding of how the con
|
|||
|
||||
The high-level overview of Docusaurus configuration can be categorized into:
|
||||
|
||||
<TOCInline toc={toc[0].children} />
|
||||
<TOCInline toc={toc} minHeadingLevel={3} maxHeadingLevel={3} />
|
||||
|
||||
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md).
|
||||
|
||||
|
|
|
@ -59,14 +59,6 @@ import TOCInline from '@theme/TOCInline';
|
|||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
|
||||
<TOCInline toc={[toc[2], toc[4]]} />
|
||||
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
:::caution
|
||||
|
|
|
@ -25,12 +25,6 @@ Once your website is bootstrapped, the website source will contain the Docusauru
|
|||
}
|
||||
```
|
||||
|
||||
## Index {#index}
|
||||
|
||||
import TOCInline from "@theme/TOCInline"
|
||||
|
||||
<TOCInline toc={toc[1].children}/>
|
||||
|
||||
## Docusaurus CLI commands {#docusaurus-cli-commands}
|
||||
|
||||
Below is a list of Docusaurus CLI commands and their usages:
|
||||
|
|
|
@ -17,7 +17,7 @@ However, it can be helpful if you have a high-level understanding of how the con
|
|||
|
||||
The high-level overview of Docusaurus configuration can be categorized into:
|
||||
|
||||
<TOCInline toc={toc[0].children} />
|
||||
<TOCInline toc={toc} minHeadingLevel={3} maxHeadingLevel={3} />
|
||||
|
||||
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md).
|
||||
|
||||
|
|
|
@ -59,12 +59,6 @@ import TOCInline from '@theme/TOCInline';
|
|||
/>;
|
||||
```
|
||||
|
||||
```mdx-code-block
|
||||
<BrowserWindow>
|
||||
<TOCInline toc={[toc[2], toc[4]]} />
|
||||
</BrowserWindow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
:::caution
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue