A fenced block names a language your highlighter did not load. Check the language before highlighting, and leave unsupported blocks as escaped code. The useful fallback is readable source, not missing content or an invented language classification.
Consider a fictional documentation note containing a JavaScript fence and a fence labeled warehouse-rule. The first names a supported programming language. The second is a source label chosen for this exercise, not a language the page should pretend to recognize.
Open the complete example · Download the full HTML source
Connect the parser's fence hook
The markdown-it 14.1.0 README documents a highlight option for fenced code. This recipe uses that pinned parser API with highlight.js:
const parser = window.markdownit({
html: false,
highlight(text, language) {
if (!language || !hljs.getLanguage(language)) return '';
return hljs.highlight(text, {language}).value;
}
});
The empty-string return asks this parser to use its normal escaping. It is not an instruction to delete the code. Keep the selected parser version with the recipe; do not assume another parser interprets the callback's return value the same way.
The highlighter and its theme are separate dependencies. Load the chosen language distribution and stylesheet before rendering. A language name in a fence cannot supply a missing language implementation.
Let the fallback preserve the text
Use the literal string <img src="example"> in the unsupported fence. The reading copy should show those characters inside the code block, not create an image element. Compare the resulting textContent with the source code string and check that no unexpected image element appeared.
Do not insert the raw code string into innerHTML as a fallback. That would turn the failure to highlight into a different rendering path with different HTML handling.
For a known-language block, inspect both the text and generated highlighting spans. Color alone is insufficient: the same visible word can survive while punctuation or indentation was lost. If your application handles a highlighter exception, keep the code and expose the diagnostic to its author rather than silently claiming the block was highlighted successfully.
Re-render from Markdown when the source changes
When an author changes the fence label from warehouse-rule to a supported language, render the current Markdown again. Retire any previous language-status label along with the old preview. An empty source should produce a clear empty state rather than retaining the last code block.
The existing highlight.js HTML guide works directly with code elements and runtime highlighting calls. This recipe concerns the parser callback, the unsupported-language return value, and escaping while Markdown becomes HTML. The markdown-it reading-copy guide handles the basic page export without this integration.
Retain the original Markdown beside the reading copy in NOS. Ask the reviewer whether the fence's language label describes the actual source. The answer determines whether color is meaningful or whether literal code is the more accurate presentation.