highlightCodeBlocks() — astro Function Reference

Architecture documentation for the highlightCodeBlocks() function in highlight.ts from the astro codebase.

Function typescript CoreAstro RenderingEngine

Entity Profile

CoreAstro→ RenderingEngine→ highlightCodeBlocks() — astro Function Reference

Dependency Diagram

graph TD
  ba780639_9373_8896_aacd_f2c31612c254["highlightCodeBlocks()"]
  5feef60c_7aec_ab11_c4dc_ea28f338b6e8["highlight.ts"]
  ba780639_9373_8896_aacd_f2c31612c254 -->|defined in| 5feef60c_7aec_ab11_c4dc_ea28f338b6e8
  style ba780639_9373_8896_aacd_f2c31612c254 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/markdown/remark/src/highlight.ts lines 26–102

export async function highlightCodeBlocks(
	tree: Root,
	highlighter: Highlighter,
	excludeLanguages: string[] = [],
) {
	const nodes: Array<{
		node: Element;
		language: string;
		parent: Element;
		grandParent: Parent;
	}> = [];

	// We’re looking for `<code>` elements
	visitParents(tree, { type: 'element', tagName: 'code' }, (node, ancestors) => {
		const parent = ancestors.at(-1);

		// Whose parent is a `<pre>`.
		if (parent?.type !== 'element' || parent.tagName !== 'pre') {
			return;
		}

		// Where the `<code>` is the only child.
		if (parent.children.length !== 1) {
			return;
		}

		// And the `<code>` has a class name that starts with `language-`.
		let languageMatch: RegExpMatchArray | null | undefined;
		let { className } = node.properties;
		if (typeof className === 'string') {
			languageMatch = languagePattern.exec(className);
		} else if (Array.isArray(className)) {
			for (const cls of className) {
				if (typeof cls !== 'string') {
					continue;
				}

				languageMatch = languagePattern.exec(cls);
				if (languageMatch) {
					break;
				}
			}
		}

		const language = languageMatch?.[1] || 'plaintext';
		if (excludeLanguages.includes(language) || defaultExcludeLanguages.includes(language)) {
			return;
		}

		nodes.push({
			node,
			language,
			parent,
			grandParent: ancestors.at(-2)!,
		});
	});

	for (const { node, language, grandParent, parent } of nodes) {
		const meta = (node.data as any)?.meta ?? node.properties.metastring ?? undefined;
		const code = toText(node, { whitespace: 'pre' });
		const result = await highlighter(code, language, { meta });

		let replacement: Element;
		if (typeof result === 'string') {
			// The replacement returns a root node with 1 child, the `<pre>` element replacement.
			replacement = fromHtml(result, { fragment: true }).children[0] as Element;
			// We just generated this node, so any positional information is invalid.
			removePosition(replacement);
		} else {
			replacement = result.children[0] as Element;
		}

		// We replace the parent in its parent with the new `<pre>` element.
		const index = grandParent.children.indexOf(parent);
		grandParent.children[index] = replacement;
	}
}