Skip to content

Commit 8cc1fd0

Browse files
authored
fix(unist): convert commented markdown into HTML (#1049)
1 parent 2592ea2 commit 8cc1fd0

13 files changed

Lines changed: 255 additions & 36 deletions

File tree

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@doc-kit/generator-react': patch
3+
'@doc-kit/core': patch
4+
---
5+
6+
Render markdown summaries as markup instead of as their source
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import assert from 'node:assert/strict';
2+
import { describe, it } from 'node:test';
3+
4+
import { parseInline, renderAsHTML } from '../inline.mjs';
5+
6+
describe('parseInline', () => {
7+
it('drops the paragraph a line of prose is parsed into', () => {
8+
const nodes = parseInline('Some `code` here.');
9+
10+
assert.deepEqual(
11+
nodes.map(node => node.type),
12+
['text', 'inlineCode', 'text']
13+
);
14+
});
15+
16+
it('replaces links with their text when asked', () => {
17+
const markdown = 'Superseded by [DEP0111](#DEP0111).';
18+
19+
assert.equal(parseInline(markdown)[1].type, 'link');
20+
assert.deepEqual(
21+
parseInline(markdown, true).map(node => node.type),
22+
['text', 'text', 'text']
23+
);
24+
});
25+
});
26+
27+
describe('renderAsHTML', () => {
28+
it('renders nodes without whitespace between them', () => {
29+
const html = renderAsHTML(parseInline('Now returns `undefined`.'));
30+
31+
assert.equal(html, 'Now returns <code>undefined</code>.');
32+
});
33+
34+
it('drops raw HTML rather than passing it through', () => {
35+
const html = renderAsHTML(parseInline('A <b>bold</b> claim.'));
36+
37+
assert.equal(html, 'A bold claim.');
38+
});
39+
});

‎packages/core/src/utils/inline.mjs‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
'use strict';
2+
3+
import rehypeStringify from 'rehype-stringify';
4+
import remarkParse from 'remark-parse';
5+
import remarkRehype from 'remark-rehype';
6+
import { unified } from 'unified';
7+
import { u as createTree } from 'unist-builder';
8+
import { SKIP, visit } from 'unist-util-visit';
9+
10+
import { lazy } from './misc.mjs';
11+
12+
/**
13+
* Renders a `root` as just its children, since content placed directly on one
14+
* is otherwise rendered with a line break between each node, which surfaces as
15+
* stray whitespace.
16+
*
17+
* @param {import('mdast-util-to-hast').State} state
18+
* @param {import('unist').Parent} node
19+
*/
20+
const inlineRoot = (state, node) => ({
21+
type: 'root',
22+
children: state.all(node),
23+
});
24+
25+
/**
26+
* Retrieves an instance of Remark configured to parse plain markdown, without
27+
* the extensions that only apply to whole documents.
28+
*/
29+
const getInlineParser = lazy(() => unified().use(remarkParse));
30+
31+
/**
32+
* Retrieves an instance of Remark configured to render inline nodes as an HTML
33+
* string. Raw HTML is dropped rather than passed through, since the result is
34+
* inserted into the page as-is.
35+
*/
36+
const getInlineRenderer = lazy(() =>
37+
unified()
38+
.use(remarkRehype, { handlers: { root: inlineRoot } })
39+
.use(rehypeStringify)
40+
);
41+
42+
/**
43+
* Parses a single line of markdown (a change description, a summary, ...) into
44+
* the inline nodes it is made of.
45+
*
46+
* @param {string} markdown - The markdown to parse.
47+
* @param {boolean} [dropLinks] - Replace links with their text? Anchors cannot
48+
* nest, so content rendered inside a link must not contain one.
49+
* @returns {Array<import('mdast').PhrasingContent>} The parsed nodes.
50+
*/
51+
export const parseInline = (markdown, dropLinks = false) => {
52+
const tree = getInlineParser().parse(markdown);
53+
54+
if (dropLinks) {
55+
visit(tree, 'link', (node, index, parent) => {
56+
parent.children.splice(index, 1, ...node.children);
57+
58+
return [SKIP, index];
59+
});
60+
}
61+
62+
const [first] = tree.children;
63+
64+
// A single line of prose parses into one paragraph, which is dropped so the
65+
// nodes can be rendered inline
66+
return tree.children.length === 1 && first.type === 'paragraph'
67+
? first.children
68+
: tree.children;
69+
};
70+
71+
/**
72+
* Renders inline nodes as an HTML string, for the places that hand rendered
73+
* markup to a component through a data channel rather than as an AST.
74+
*
75+
* @param {Array<import('mdast').PhrasingContent>} nodes - The nodes to render.
76+
* @returns {string} The rendered HTML.
77+
*/
78+
export const renderAsHTML = nodes => {
79+
const renderer = getInlineRenderer();
80+
81+
return renderer.stringify(renderer.runSync(createTree('root', nodes)));
82+
};

‎packages/react/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
"@heroicons/react": "^2.2.0",
3535
"@doc-kit/core": "workspace:*",
3636
"@node-core/rehype-shiki": "^1.4.3",
37-
"@node-core/ui-components": "^1.7.4",
37+
"@node-core/ui-components": "^1.7.6",
3838
"@orama/orama": "^3.1.18",
3939
"@orama/ui": "^1.5.4",
4040
"estree-util-to-js": "^2.0.0",

‎packages/react/src/html/ui/components/DocumentationIndex/index.jsx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ import { documentationIndex } from '#theme/config';
1010
* @property {string} api - Basename of the document, linked as `${api}.html`
1111
* @property {string} name - Human-readable name from the document's heading
1212
* @property {string} index - Stability index (e.g. `'2'` or `'1.1'`)
13-
* @property {string} [description] - The document's `llm_description`, or its first paragraph
13+
* @property {string} [description] - The document's `llm_description`, or its
14+
* first paragraph, rendered to HTML at build time
1415
*/
1516

1617
/**
@@ -34,7 +35,13 @@ const IndexEntry = ({ api, name, index, description }) => {
3435
</Badge>
3536
</span>
3637

37-
{description && <span className={styles.summary}>{description}</span>}
38+
{description && (
39+
<span
40+
className={styles.summary}
41+
// Rendered from the document's own markdown at build time
42+
dangerouslySetInnerHTML={{ __html: description }}
43+
/>
44+
)}
3845
</a>
3946
);
4047
};

‎packages/react/src/html/utils/__tests__/config.test.mjs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,29 @@ describe('buildDocumentationIndex', () => {
185185
},
186186
]);
187187
});
188+
189+
it('renders descriptions to HTML, without the links entries cannot nest', () => {
190+
const input = [
191+
{
192+
data: {
193+
api: 'fs',
194+
path: '/fs',
195+
heading: { depth: 1, data: { name: 'File System' } },
196+
stability: { data: { index: '2' } },
197+
llm_description:
198+
'Enables interacting with the `file system`, see [fs](/fs).',
199+
content: { type: 'root', children: [] },
200+
},
201+
},
202+
];
203+
204+
const [{ description }] = buildDocumentationIndex(input);
205+
206+
assert.equal(
207+
description,
208+
'Enables interacting with the <code>file system</code>, see fs.'
209+
);
210+
});
188211
});
189212

190213
describe('buildLanguageDisplayNameMap', () => {

‎packages/react/src/html/utils/config.mjs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
getEntryDescription,
77
getVersionFromSemVer,
88
} from '@doc-kit/core/utils/generators.mjs';
9+
import { parseInline, renderAsHTML } from '@doc-kit/core/utils/inline.mjs';
910
import { omitKeys } from '@doc-kit/core/utils/misc.mjs';
1011
import { LANGS } from '@node-core/rehype-shiki';
1112

@@ -58,7 +59,7 @@ export function buildDocumentationIndex(input) {
5859
api: entry.api,
5960
name: entry.heading.data.name,
6061
index: entry.stability.data.index,
61-
description: getEntryDescription(entry),
62+
description: renderAsHTML(parseInline(getEntryDescription(entry), true)),
6263
}));
6364
}
6465

‎packages/react/src/jsx-ast/utils/__tests__/buildContent.test.mjs‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,18 @@ const makeParent = typeText => ({
2222
],
2323
});
2424

25+
/**
26+
* Collects the tag names of every JSX element within a JSX AST node.
27+
*
28+
* @param {import('estree-jsx').JSXFragment} node
29+
*/
30+
const jsxElementNames = node =>
31+
(node.children ?? []).flatMap(child =>
32+
child.type === 'JSXElement'
33+
? [child.openingElement.name.name, ...jsxElementNames(child)]
34+
: jsxElementNames(child)
35+
);
36+
2537
await setConfig({});
2638

2739
describe('transformHeadingNode (deprecation Type -> AlertBox level)', () => {
@@ -111,6 +123,42 @@ describe('gatherChangeEntries', () => {
111123
assert.deepEqual(result[0].versions, ['v25.0.0']);
112124
});
113125

126+
it('renders the markdown description as JSX content', () => {
127+
const [change] = gatherChangeEntries({
128+
changes: [
129+
{
130+
version: 'v25.0.0',
131+
description: 'Add `modifyPrototype` option.',
132+
},
133+
],
134+
});
135+
136+
assert.equal(change.content.type, 'JSXFragment');
137+
assert.deepEqual(jsxElementNames(change.content), ['code']);
138+
});
139+
140+
it('unwraps description links when the change links to its pull request', () => {
141+
const description = 'Superseded by [DEP0111](#DEP0111).';
142+
143+
const [linked] = gatherChangeEntries({
144+
changes: [
145+
{
146+
version: 'v1.0.0',
147+
description,
148+
'pr-url': 'https://example.com/pr/1',
149+
},
150+
],
151+
});
152+
153+
const [unlinked] = gatherChangeEntries({
154+
changes: [{ version: 'v1.0.0', description }],
155+
});
156+
157+
assert.deepEqual(jsxElementNames(linked.content), []);
158+
assert.deepEqual(jsxElementNames(unlinked.content), ['a']);
159+
assert.equal(linked.label, 'Superseded by DEP0111.');
160+
});
161+
114162
it('produces a string label, not an object (regression for [object Object])', () => {
115163
const result = gatherChangeEntries({
116164
changes: [

‎packages/react/src/jsx-ast/utils/buildContent.mjs‎

Lines changed: 17 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,20 @@ import {
66
GITHUB_BLOB_URL,
77
populate,
88
} from '@doc-kit/core/utils/configuration/templates.mjs';
9+
import { parseInline } from '@doc-kit/core/utils/inline.mjs';
910
import { omitKeys } from '@doc-kit/core/utils/misc.mjs';
1011
import { UNIST } from '@doc-kit/core/utils/queries/index.mjs';
1112
import { transformNodesToString } from '@doc-kit/core/utils/unist.mjs';
1213
import { h as createElement } from 'hastscript';
1314
import { slice } from 'mdast-util-slice-markdown';
14-
import remarkParse from 'remark-parse';
15-
import { unified } from 'unified';
1615
import { u as createTree } from 'unist-builder';
1716
import { SKIP, visit } from 'unist-util-visit';
1817

1918
import { createJSXElement } from './ast.mjs';
2019
import { extractHeadings, extractTextContent } from './buildBarProps.mjs';
2120
import { annotateOverloads } from './overloads.mjs';
2221
import { getRemarkRecma as remark } from './remark.mjs';
22+
import { renderAsJSX } from './render.mjs';
2323
import { JSX_IMPORTS } from '../../html/constants.mjs';
2424
import {
2525
STABILITY_LEVELS,
@@ -37,18 +37,6 @@ import {
3737
getFullName,
3838
} from './signature.mjs';
3939

40-
/**
41-
* Converts a markdown string to plain text by parsing it and extracting
42-
* text and inline code values.
43-
*
44-
* @param {string} markdown - The markdown string to convert.
45-
* @returns {string} The plain text representation.
46-
*/
47-
const toPlainText = markdown =>
48-
transformNodesToString(
49-
unified().use(remarkParse).parse(markdown).children
50-
).trim();
51-
5240
/**
5341
*
5442
*/
@@ -68,12 +56,21 @@ export const gatherChangeEntries = entry => {
6856
label: `${label}: ${enforceArray(entry[field]).join(', ')}`,
6957
}));
7058

71-
// Explicit changes with plain-text labels extracted from markdown
72-
const explicitChanges = (entry.changes || []).map(change => ({
73-
versions: enforceArray(change.version),
74-
label: toPlainText(change.description),
75-
url: change['pr-url'],
76-
}));
59+
// Explicit changes, whose markdown descriptions are rendered as JSX
60+
const explicitChanges = (entry.changes || []).map(change => {
61+
const url = change['pr-url'];
62+
const nodes = parseInline(change.description, Boolean(url));
63+
64+
return {
65+
versions: enforceArray(change.version),
66+
// The plain text backs the change's `aria-label` and React key
67+
label: transformNodesToString(nodes).trim(),
68+
// `content` takes a ReactNode, so inline code, emphasis and links are
69+
// displayed as markup instead of as their markdown source
70+
content: renderAsJSX(nodes),
71+
url,
72+
};
73+
});
7774

7875
return [...lifecycleChanges, ...explicitChanges];
7976
};
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
'use strict';
2+
3+
import { u as createTree } from 'unist-builder';
4+
5+
import { createJSXElement } from './ast.mjs';
6+
import { getRemarkRecma as remark } from './remark.mjs';
7+
8+
/**
9+
* Renders inline nodes as a JSX fragment
10+
*
11+
* @param {Array<import('mdast').PhrasingContent>} nodes - The nodes to render.
12+
* @returns {import('estree-jsx').JSXFragment} The rendered nodes.
13+
*/
14+
export const renderAsJSX = nodes =>
15+
remark().runSync(
16+
createTree('root', [createJSXElement(null, { children: nodes })])
17+
).body[0].expression;

0 commit comments

Comments
 (0)