3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-25 12:38:57 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(theme-classic): extensible code block magic comment system (#7178)

Browse source
This commit is contained in:
Joshua Chen 2022-05-04 18:31:13 +08:00 • committed by GitHub
parent 785fed723f
commit 51815c12c9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 692 additions and 161 deletions
Download patch file Download diff file Expand all files Collapse all files

225
packages/docusaurus-theme-common/src/utils/__tests__/__snapshots__/codeBlockUtils.test.ts.snap
View file

@ -4,9 +4,11 @@ exports[`parseLines does not parse content with metastring 1`] = `
{
"code": "aaaaa
nnnnn",
"highlightLines": [
0,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -15,9 +17,11 @@ exports[`parseLines does not parse content with metastring 2`] = `
"code": "// highlight-next-line
aaaaa
bbbbb",
"highlightLines": [
0,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -25,9 +29,11 @@ exports[`parseLines does not parse content with metastring 3`] = `
{
"code": "aaaaa
bbbbb",
"highlightLines": [
0,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -36,7 +42,100 @@ exports[`parseLines does not parse content with no language 1`] = `
"code": "// highlight-next-line
aaaaa
bbbbb",
"highlightLines": [],
"lineClassNames": {},
}
`;
exports[`parseLines handles one line with multiple class names 1`] = `
{
"code": "
highlighted and collapsed
highlighted and collapsed
highlighted and collapsed
Only highlighted
Only collapsed
highlighted and collapsed
highlighted and collapsed
Only collapsed
highlighted and collapsed",
"lineClassNames": {
"1": [
"highlight",
"collapse",
],
"2": [
"highlight",
"collapse",
],
"3": [
"highlight",
"collapse",
],
"4": [
"highlight",
],
"5": [
"collapse",
],
"6": [
"highlight",
"collapse",
],
"7": [
"highlight",
"collapse",
],
"8": [
"collapse",
],
"9": [
"highlight",
"collapse",
],
},
}
`;
exports[`parseLines handles one line with multiple class names 2`] = `
{
"code": "line
line",
"lineClassNames": {
"0": [
"a",
"b",
"c",
"d",
],
"1": [
"b",
"d",
],
},
}
`;
exports[`parseLines parses multiple types of magic comments 1`] = `
{
"code": "
highlighted
collapsed
collapsed
collapsed",
"lineClassNames": {
"1": [
"highlight",
],
"2": [
"collapse",
],
"3": [
"collapse",
],
"4": [
"collapse",
],
},
}
`;
@ -44,9 +143,11 @@ exports[`parseLines removes lines correctly 1`] = `
{
"code": "aaaaa
bbbbb",
"highlightLines": [
0,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -54,9 +155,11 @@ exports[`parseLines removes lines correctly 2`] = `
{
"code": "aaaaa
bbbbb",
"highlightLines": [
0,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -65,12 +168,18 @@ exports[`parseLines removes lines correctly 3`] = `
"code": "aaaaa
bbbbbbb
bbbbb",
"highlightLines": [
0,
2,
0,
1,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
"theme-code-block-highlighted-line",
],
"1": [
"theme-code-block-highlighted-line",
],
"2": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -80,10 +189,14 @@ exports[`parseLines respects language: html 1`] = `
{/* highlight-next-line */}
bbbbb
dddd",
"highlightLines": [
0,
3,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
"3": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -92,7 +205,7 @@ exports[`parseLines respects language: js 1`] = `
"code": "# highlight-next-line
aaaaa
bbbbb",
"highlightLines": [],
"lineClassNames": {},
}
`;
@ -102,10 +215,14 @@ exports[`parseLines respects language: jsx 1`] = `
bbbbb
<!-- highlight-next-line -->
dddd",
"highlightLines": [
0,
1,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
"1": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -128,11 +245,17 @@ dddd
// highlight-next-line
console.log("preserved");
\`\`\`",
"highlightLines": [
1,
7,
11,
],
"lineClassNames": {
"1": [
"theme-code-block-highlighted-line",
],
"11": [
"theme-code-block-highlighted-line",
],
"7": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -142,12 +265,20 @@ exports[`parseLines respects language: none 1`] = `
bbbbb
ccccc
dddd",
"highlightLines": [
0,
1,
2,
3,
],
"lineClassNames": {
"0": [
"theme-code-block-highlighted-line",
],
"1": [
"theme-code-block-highlighted-line",
],
"2": [
"theme-code-block-highlighted-line",
],
"3": [
"theme-code-block-highlighted-line",
],
},
}
`;
@ -156,7 +287,7 @@ exports[`parseLines respects language: py 1`] = `
"code": "/* highlight-next-line */
aaaaa
bbbbb",
"highlightLines": [],
"lineClassNames": {},
}
`;
@ -169,8 +300,10 @@ bbbbb
ccccc
<!-- highlight-next-line -->
dddd",
"highlightLines": [
4,
],
"lineClassNames": {
"4": [
"theme-code-block-highlighted-line",
],
},
}
`;

181
packages/docusaurus-theme-common/src/utils/__tests__/codeBlockUtils.test.ts
View file

@ -6,6 +6,7 @@
*/
import {
type MagicCommentConfig,
parseCodeBlockTitle,
parseLanguage,
parseLines,
@ -67,24 +68,58 @@ describe('parseLanguage', () => {
});
describe('parseLines', () => {
const defaultMagicComments: MagicCommentConfig[] = [
{
className: 'theme-code-block-highlighted-line',
line: 'highlight-next-line',
block: {start: 'highlight-start', end: 'highlight-end'},
},
];
it('does not parse content with metastring', () => {
expect(parseLines('aaaaa\nnnnnn', '{1}', 'js')).toMatchSnapshot();
expect(
parseLines('aaaaa\nnnnnn', {
metastring: '{1}',
language: 'js',
magicComments: defaultMagicComments,
}),
).toMatchSnapshot();
expect(
parseLines(
`// highlight-next-line
aaaaa
bbbbb`,
'{1}',
'js',
{
metastring: '{1}',
language: 'js',
magicComments: defaultMagicComments,
},
),
).toMatchSnapshot();
expect(
parseLines(
`aaaaa
bbbbb`,
'{1}',
{
metastring: '{1}',
language: 'undefined',
magicComments: defaultMagicComments,
},
),
).toMatchSnapshot();
expect(() =>
parseLines(
`aaaaa
bbbbb`,
{
metastring: '{1}',
language: 'js',
magicComments: [],
},
),
).toThrowErrorMatchingInlineSnapshot(
`"A highlight range has been given in code block's metastring (\`\`\` {1}), but no magic comment config is available. Docusaurus applies the first magic comment entry's className for metastring ranges."`,
);
});
it('does not parse content with no language', () => {
expect(
@ -92,8 +127,11 @@ bbbbb`,
`// highlight-next-line
aaaaa
bbbbb`,
'',
undefined,
{
metastring: '',
language: undefined,
magicComments: defaultMagicComments,
},
),
).toMatchSnapshot();
});
@ -103,8 +141,7 @@ bbbbb`,
`// highlight-next-line
aaaaa
bbbbb`,
'',
'js',
{metastring: '', language: 'js', magicComments: defaultMagicComments},
),
).toMatchSnapshot();
expect(
@ -113,8 +150,7 @@ bbbbb`,
aaaaa
// highlight-end
bbbbb`,
'',
'js',
{metastring: '', language: 'js', magicComments: defaultMagicComments},
),
).toMatchSnapshot();
expect(
@ -126,8 +162,7 @@ bbbbbbb
// highlight-next-line
// highlight-end
bbbbb`,
'',
'js',
{metastring: '', language: 'js', magicComments: defaultMagicComments},
),
).toMatchSnapshot();
});
@ -137,8 +172,7 @@ bbbbb`,
`# highlight-next-line
aaaaa
bbbbb`,
'',
'js',
{metastring: '', language: 'js', magicComments: defaultMagicComments},
),
).toMatchSnapshot('js');
expect(
@ -146,8 +180,7 @@ bbbbb`,
`/* highlight-next-line */
aaaaa
bbbbb`,
'',
'py',
{metastring: '', language: 'py', magicComments: defaultMagicComments},
),
).toMatchSnapshot('py');
expect(
@ -160,8 +193,7 @@ bbbbb
ccccc
<!-- highlight-next-line -->
dddd`,
'',
'py',
{metastring: '', language: 'py', magicComments: defaultMagicComments},
),
).toMatchSnapshot('py');
expect(
@ -174,8 +206,7 @@ bbbbb
ccccc
<!-- highlight-next-line -->
dddd`,
'',
'',
{metastring: '', language: '', magicComments: defaultMagicComments},
),
).toMatchSnapshot('none');
expect(
@ -186,8 +217,7 @@ aaaa
bbbbb
<!-- highlight-next-line -->
dddd`,
'',
'jsx',
{metastring: '', language: 'jsx', magicComments: defaultMagicComments},
),
).toMatchSnapshot('jsx');
expect(
@ -198,8 +228,7 @@ aaaa
bbbbb
<!-- highlight-next-line -->
dddd`,
'',
'html',
{metastring: '', language: 'html', magicComments: defaultMagicComments},
),
).toMatchSnapshot('html');
expect(
@ -225,9 +254,109 @@ dddd
console.log("preserved");
\`\`\`
`,
'',
'md',
{metastring: '', language: 'md', magicComments: defaultMagicComments},
),
).toMatchSnapshot('md');
});
it('parses multiple types of magic comments', () => {
expect(
parseLines(
`
// highlight-next-line
highlighted
// collapse-next-line
collapsed
/* collapse-start */
collapsed
collapsed
/* collapse-end */
`,
{
language: 'js',
metastring: '',
magicComments: [
{
className: 'highlight',
line: 'highlight-next-line',
block: {start: 'highlight-start', end: 'highlight-end'},
},
{
className: 'collapse',
line: 'collapse-next-line',
block: {start: 'collapse-start', end: 'collapse-end'},
},
],
},
),
).toMatchSnapshot();
});
it('handles one line with multiple class names', () => {
expect(
parseLines(
`
// highlight-next-line
// collapse-next-line
highlighted and collapsed
/* collapse-start */
/* highlight-start */
highlighted and collapsed
highlighted and collapsed
/* collapse-end */
Only highlighted
/* highlight-end */
/* collapse-start */
Only collapsed
/* highlight-start */
highlighted and collapsed
highlighted and collapsed
/* highlight-end */
Only collapsed
// highlight-next-line
highlighted and collapsed
/* collapse-end */
`,
{
language: 'js',
metastring: '',
magicComments: [
{
className: 'highlight',
line: 'highlight-next-line',
block: {start: 'highlight-start', end: 'highlight-end'},
},
{
className: 'collapse',
line: 'collapse-next-line',
block: {start: 'collapse-start', end: 'collapse-end'},
},
],
},
),
).toMatchSnapshot();
expect(
parseLines(
`// a
// b
// c
// d
line
// b
// d
line
`,
{
language: 'js',
metastring: '',
magicComments: [
{className: 'a', line: 'a'},
{className: 'b', line: 'b'},
{className: 'c', line: 'c'},
{className: 'd', line: 'd'},
],
},
),
).toMatchSnapshot();
});
});

169
packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts
View file

@ -10,7 +10,7 @@ import type {PrismTheme} from 'prism-react-renderer';
import type {CSSProperties} from 'react';
const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
const highlightLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
const metastringLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
// Supported types of highlight comments
const commentPatterns = {
@ -23,18 +23,23 @@ const commentPatterns = {
type CommentType = keyof typeof commentPatterns;
const magicCommentDirectives = [
'highlight-next-line',
'highlight-start',
'highlight-end',
];
export type MagicCommentConfig = {
className: string;
line?: string;
block?: {start: string; end: string};
};
function getCommentPattern(languages: CommentType[]) {
function getCommentPattern(
languages: CommentType[],
magicCommentDirectives: MagicCommentConfig[],
) {
// To be more reliable, the opening and closing comment must match
const commentPattern = languages
.map((lang) => {
const {start, end} = commentPatterns[lang];
return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`;
return `(?:${start}\\s*(${magicCommentDirectives
.flatMap((d) => [d.line, d.block?.start, d.block?.end].filter(Boolean))
.join('|')})\\s*${end})`;
})
.join('|');
// White space is allowed, but otherwise it should be on it's own line
@ -44,34 +49,46 @@ function getCommentPattern(languages: CommentType[]) {
/**
* Select comment styles based on language
*/
function getAllMagicCommentDirectiveStyles(lang: string) {
function getAllMagicCommentDirectiveStyles(
lang: string,
magicCommentDirectives: MagicCommentConfig[],
) {
switch (lang) {
case 'js':
case 'javascript':
case 'ts':
case 'typescript':
return getCommentPattern(['js', 'jsBlock']);
return getCommentPattern(['js', 'jsBlock'], magicCommentDirectives);
case 'jsx':
case 'tsx':
return getCommentPattern(['js', 'jsBlock', 'jsx']);
return getCommentPattern(
['js', 'jsBlock', 'jsx'],
magicCommentDirectives,
);
case 'html':
return getCommentPattern(['js', 'jsBlock', 'html']);
return getCommentPattern(
['js', 'jsBlock', 'html'],
magicCommentDirectives,
);
case 'python':
case 'py':
case 'bash':
return getCommentPattern(['bash']);
return getCommentPattern(['bash'], magicCommentDirectives);
case 'markdown':
case 'md':
// Text uses HTML, front matter uses bash
return getCommentPattern(['html', 'jsx', 'bash']);
return getCommentPattern(['html', 'jsx', 'bash'], magicCommentDirectives);
default:
// All comment types
return getCommentPattern(Object.keys(commentPatterns) as CommentType[]);
return getCommentPattern(
Object.keys(commentPatterns) as CommentType[],
magicCommentDirectives,
);
}
}
@ -99,50 +116,91 @@ export function parseLanguage(className: string): string | undefined {
* Parses the code content, strips away any magic comments, and returns the
* clean content and the highlighted lines marked by the comments or metastring.
*
* If the metastring contains highlight range, the `content` will be returned
* as-is without any parsing.
* If the metastring contains a range, the `content` will be returned as-is
* without any parsing. The returned `lineClassNames` will be a map from that
* number range to the first magic comment config entry (which _should_ be for
* line highlight directives.)
*
* @param content The raw code with magic comments. Trailing newline will be
* trimmed upfront.
* @param metastring The full metastring, as received from MDX. Highlight range
* declared here starts at 1.
* @param language Language of the code block, used to determine which kinds of
* magic comment styles to enable.
* @param options Options for parsing behavior.
*/
export function parseLines(
content: string,
metastring?: string,
language?: string,
options: {
/**
* The full metastring, as received from MDX. Line ranges declared here
* start at 1.
*/
metastring: string | undefined;
/**
* Language of the code block, used to determine which kinds of magic
* comment styles to enable.
*/
language: string | undefined;
/**
* Magic comment types that we should try to parse. Each entry would
* correspond to one class name to apply to each line.
*/
magicComments: MagicCommentConfig[];
},
): {
/**
* The highlighted lines, 0-indexed. e.g. `[0, 1, 4]` means the 1st, 2nd, and
* 5th lines are highlighted.
* The highlighted lines, 0-indexed. e.g. `{ 0: ["highlight", "sample"] }`
* means the 1st line should have `highlight` and `sample` as class names.
*/
highlightLines: number[];
lineClassNames: {[lineIndex: number]: string[]};
/**
* The clean code without any magic comments (only if highlight range isn't
* present in the metastring).
* If there's number range declared in the metastring, the code block is
* returned as-is (no parsing); otherwise, this is the clean code with all
* magic comments stripped away.
*/
code: string;
} {
let code = content.replace(/\n$/, '');
const {language, magicComments, metastring} = options;
// Highlighted lines specified in props: don't parse the content
if (metastring && highlightLinesRangeRegex.test(metastring)) {
const highlightLinesRange = metastring.match(highlightLinesRangeRegex)!
.groups!.range!;
const highlightLines = rangeParser(highlightLinesRange)
if (metastring && metastringLinesRangeRegex.test(metastring)) {
const linesRange = metastring.match(metastringLinesRangeRegex)!.groups!
.range!;
if (magicComments.length === 0) {
throw new Error(
`A highlight range has been given in code block's metastring (\`\`\` ${metastring}), but no magic comment config is available. Docusaurus applies the first magic comment entry's className for metastring ranges.`,
);
}
const metastringRangeClassName = magicComments[0]!.className;
const lines = rangeParser(linesRange)
.filter((n) => n > 0)
.map((n) => n - 1);
return {highlightLines, code};
.map((n) => [n - 1, [metastringRangeClassName]]);
return {lineClassNames: Object.fromEntries(lines), code};
}
if (language === undefined) {
return {highlightLines: [], code};
return {lineClassNames: {}, code};
}
const directiveRegex = getAllMagicCommentDirectiveStyles(language);
const directiveRegex = getAllMagicCommentDirectiveStyles(
language,
magicComments,
);
// Go through line by line
const lines = code.split('\n');
let highlightBlockStart: number;
let highlightRange = '';
const blocks = Object.fromEntries(
magicComments.map((d) => [d.className, {start: 0, range: ''}]),
);
const lineToClassName: {[comment: string]: string} = Object.fromEntries(
magicComments
.filter((d) => d.line)
.map(({className, line}) => [line, className]),
);
const blockStartToClassName: {[comment: string]: string} = Object.fromEntries(
magicComments
.filter((d) => d.block)
.map(({className, block}) => [block!.start, className]),
);
const blockEndToClassName: {[comment: string]: string} = Object.fromEntries(
magicComments
.filter((d) => d.block)
.map(({className, block}) => [block!.end, className]),
);
for (let lineNumber = 0; lineNumber < lines.length; ) {
const line = lines[lineNumber]!;
const match = line.match(directiveRegex);
@ -151,28 +209,27 @@ export function parseLines(
lineNumber += 1;
continue;
}
const directive = match.slice(1).find((item) => item !== undefined);
switch (directive) {
case 'highlight-next-line':
highlightRange += `${lineNumber},`;
break;
case 'highlight-start':
highlightBlockStart = lineNumber;
break;
case 'highlight-end':
highlightRange += `${highlightBlockStart!}-${lineNumber - 1},`;
break;
default:
break;
const directive = match.slice(1).find((item) => item !== undefined)!;
if (lineToClassName[directive]) {
blocks[lineToClassName[directive]!]!.range += `${lineNumber},`;
} else if (blockStartToClassName[directive]) {
blocks[blockStartToClassName[directive]!]!.start = lineNumber;
} else if (blockEndToClassName[directive]) {
blocks[blockEndToClassName[directive]!]!.range += `${
blocks[blockEndToClassName[directive]!]!.start
}-${lineNumber - 1},`;
}
lines.splice(lineNumber, 1);
}
const highlightLines = rangeParser(highlightRange);
code = lines.join('\n');
return {highlightLines, code};
const lineClassNames: {[lineIndex: number]: string[]} = {};
Object.entries(blocks).forEach(([className, {range}]) => {
rangeParser(range).forEach((l) => {
lineClassNames[l] ??= [];
lineClassNames[l]!.push(className);
});
});
return {lineClassNames, code};
}
export function getPrismCssVariables(prismTheme: PrismTheme): CSSProperties {

2
packages/docusaurus-theme-common/src/utils/useThemeConfig.ts
View file

@ -8,6 +8,7 @@
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import type {PrismTheme} from 'prism-react-renderer';
import type {DeepPartial} from 'utility-types';
import type {MagicCommentConfig} from './codeBlockUtils';
export type DocsVersionPersistence = 'localStorage' | 'none';
@ -57,6 +58,7 @@ export type PrismConfig = {
darkTheme?: PrismTheme;
defaultLanguage?: string;
additionalLanguages: string[];
magicComments: MagicCommentConfig[];
};
export type FooterLinkItem = {