3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-27 21:48:41 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(v2): inline table-of-contents + refactor TOC (#3904)

Browse source 
* Add TOCInline theme component

* Add TOCInline theme component doc + migration guide

* remove useless getPathsToWatch on classic theme

* rename rightToc to toc

* add temp theme-bootstrap TOCInline comp to fix build issue
This commit is contained in:
Sébastien Lorber 2020-12-11 16:30:53 +01:00 • committed by GitHub
parent b11c24b752
commit 41ef333e47
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 206 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

85
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/__snapshots__/index.test.js.snap Normal file
View file

@ -0,0 +1,85 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`inline code should be escaped 1`] = `
"export const toc = [
{
value: '<code>&lt;Head /&gt;</code>',
id: 'head-',
children: [
{
value: '<code>&lt;Head&gt;Test&lt;/Head&gt;</code>',
id: 'headtesthead',
children: []
}
]
},
{
value: '<code>&lt;div /&gt;</code>',
id: 'div-',
children: []
},
{
value: '<code>&lt;div&gt; Test &lt;/div&gt;</code>',
id: 'div-test-div',
children: []
},
{
value: '<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>',
id: 'divitestidiv',
children: []
}
];
## \`<Head />\`
### \`<Head>Test</Head>\`
## \`<div />\`
## \`<div> Test </div>\`
## \`<div><i>Test</i></div>\`
"
`;
exports[`non text phrasing content 1`] = `
"export const toc = [
{
value: '<em>Emphasis</em>',
id: 'emphasis',
children: [
{
value: '<strong>Importance</strong>',
id: 'importance',
children: []
}
]
},
{
value: '<del>Strikethrough</del>',
id: 'strikethrough',
children: []
},
{
value: '<i>HTML</i>',
id: 'html',
children: []
},
{
value: '<code>inline.code()</code>',
id: 'inlinecode',
children: []
}
];
## _Emphasis_
### **Importance**
## ~~Strikethrough~~
## <i>HTML</i>
## \`inline.code()\`
"
`;

5
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/empty-headings.md Normal file
View file

@ -0,0 +1,5 @@
# Ignore this
##
## ![](an-image.svg)

9
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/inline-code.md Normal file
View file

@ -0,0 +1,9 @@
## `<Head />`
### `<Head>Test</Head>`
## `<div />`
## `<div> Test </div>`
## `<div><i>Test</i></div>`

11
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/insert-below-imports.md Normal file
View file

@ -0,0 +1,11 @@
import something from 'something';
import somethingElse from 'something-else';
## Title
## Test
### Again
Content.

15
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/just-content.md Normal file
View file

@ -0,0 +1,15 @@
### Endi
```md
## This is ignored
```
## Endi
Lorem ipsum
### Yangshun
Some content here
## I ♥ unicode.

7
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/name-exist.md Normal file
View file

@ -0,0 +1,7 @@
export const toc = ['replaceMe'];
## Thanos
## Tony Stark
### Avengers

9
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/fixtures/non-text-content.md Normal file
View file

@ -0,0 +1,9 @@
## _Emphasis_
### **Importance**
## ~~Strikethrough~~
## <i>HTML</i>
## `inline.code()`

212
packages/docusaurus-mdx-loader/src/remark/toc/__tests__/index.test.js Normal file
View file

@ -0,0 +1,212 @@
/**
* 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 {join} from 'path';
import remark from 'remark';
import mdx from 'remark-mdx';
import vfile from 'to-vfile';
import plugin from '../index';
import slug from '../../slug/index';
const processFixture = async (name, options) => {
const path = join(__dirname, 'fixtures', `${name}.md`);
const file = await vfile.read(path);
const result = await remark()
.use(slug)
.use(mdx)
.use(plugin, options)
.process(file);
return result.toString();
};
test('non text phrasing content', async () => {
const result = await processFixture('non-text-content');
expect(result).toMatchSnapshot();
});
test('inline code should be escaped', async () => {
const result = await processFixture('inline-code');
expect(result).toMatchSnapshot();
});
test('text content', async () => {
const result = await processFixture('just-content');
expect(result).toMatchInlineSnapshot(`
"export const toc = [
{
value: 'Endi',
id: 'endi',
children: []
},
{
value: 'Endi',
id: 'endi-1',
children: [
{
value: 'Yangshun',
id: 'yangshun',
children: []
}
]
},
{
value: 'I ♥ unicode.',
id: 'i--unicode',
children: []
}
];
### Endi
\`\`\`md
## This is ignored
\`\`\`
## Endi
Lorem ipsum
### Yangshun
Some content here
## I ♥ unicode.
"
`);
});
test('should export even with existing name', async () => {
const result = await processFixture('name-exist');
expect(result).toMatchInlineSnapshot(`
"export const toc = [
{
value: 'Thanos',
id: 'thanos',
children: []
},
{
value: 'Tony Stark',
id: 'tony-stark',
children: [
{
value: 'Avengers',
id: 'avengers',
children: []
}
]
}
];
## Thanos
## Tony Stark
### Avengers
"
`);
});
test('should export with custom name', async () => {
const options = {
name: 'customName',
};
const result = await processFixture('just-content', options);
expect(result).toMatchInlineSnapshot(`
"export const customName = [
{
value: 'Endi',
id: 'endi',
children: []
},
{
value: 'Endi',
id: 'endi-1',
children: [
{
value: 'Yangshun',
id: 'yangshun',
children: []
}
]
},
{
value: 'I ♥ unicode.',
id: 'i--unicode',
children: []
}
];
### Endi
\`\`\`md
## This is ignored
\`\`\`
## Endi
Lorem ipsum
### Yangshun
Some content here
## I ♥ unicode.
"
`);
});
test('should insert below imports', async () => {
const result = await processFixture('insert-below-imports');
expect(result).toMatchInlineSnapshot(`
"import something from 'something';
import somethingElse from 'something-else';
export const toc = [
{
value: 'Title',
id: 'title',
children: []
},
{
value: 'Test',
id: 'test',
children: [
{
value: 'Again',
id: 'again',
children: []
}
]
}
];
## Title
## Test
### Again
Content.
"
`);
});
test('empty headings', async () => {
const result = await processFixture('empty-headings');
expect(result).toMatchInlineSnapshot(`
"export const toc = [];
# Ignore this
##
## ![](an-image.svg)
"
`);
});

79
packages/docusaurus-mdx-loader/src/remark/toc/index.js Normal file
View file

@ -0,0 +1,79 @@
/**
* 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.
*/
const {parse} = require('@babel/parser');
const traverse = require('@babel/traverse').default;
const stringifyObject = require('stringify-object');
const search = require('./search');
const parseOptions = {
plugins: ['jsx'],
sourceType: 'module',
};
const isImport = (child) => child.type === 'import';
const hasImports = (index) => index > -1;
const isExport = (child) => child.type === 'export';
const isTarget = (child, name) => {
let found = false;
const ast = parse(child.value, parseOptions);
traverse(ast, {
VariableDeclarator: (path) => {
if (path.node.id.name === name) {
found = true;
}
},
});
return found;
};
const getOrCreateExistingTargetIndex = (children, name) => {
let importsIndex = -1;
let targetIndex = -1;
children.forEach((child, index) => {
if (isImport(child)) {
importsIndex = index;
} else if (isExport(child) && isTarget(child, name)) {
targetIndex = index;
}
});
if (targetIndex === -1) {
const target = {
default: false,
type: 'export',
value: `export const ${name} = [];`,
};
targetIndex = hasImports(importsIndex) ? importsIndex + 1 : 0;
children.splice(targetIndex, 0, target);
}
return targetIndex;
};
const plugin = (options = {}) => {
const name = options.name || 'toc';
const transformer = (node) => {
const headings = search(node);
const {children} = node;
const targetIndex = getOrCreateExistingTargetIndex(children, name);
if (headings && headings.length) {
children[targetIndex].value = `export const ${name} = ${stringifyObject(
headings,
)};`;
}
};
return transformer;
};
module.exports = plugin;

71
packages/docusaurus-mdx-loader/src/remark/toc/search.js Normal file
View file

@ -0,0 +1,71 @@
/**
* 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.
*/
// @ts-check
const toString = require('mdast-util-to-string');
const visit = require('unist-util-visit');
const {toValue} = require('../utils');
/** @typedef {import('@docusaurus/types').TOCItem} TOC */
/** @typedef {import('unist').Node} Node */
/**
* @typedef {Object} StringValuedNode
* @property {string} type
* @property {string} value
* @property {number} depth
* @property {Object} data
* @property {StringValuedNode[]} children
*/
// Visit all headings. We `slug` all headings (to account for
// duplicates), but only take h2 and h3 headings.
/**
* @param {StringValuedNode} node
* @returns {TOC[]}
*/
function search(node) {
/** @type {TOC[]} */
const headings = [];
let current = -1;
let currentDepth = 0;
/**
* @param {StringValuedNode} child
* @param {number} index
* @param {Node | undefined} parent
* @returns {void}
*/
const onHeading = (child, index, parent) => {
const value = toString(child);
if (parent !== node || !value || child.depth > 3 || child.depth < 2) {
return;
}
const entry = {
value: toValue(child),
id: child.data.id,
children: [],
};
if (!headings.length || currentDepth >= child.depth) {
headings.push(entry);
current += 1;
currentDepth = child.depth;
} else {
headings[current].children.push(entry);
}
};
visit(node, 'heading', onHeading);
return headings;
}
module.exports = search;