fix: render code blocks with unknown language as plain text (#927)

Godefroy · petyosi · web-flow · commit f4785093fcfd · 2026-04-19T09:59:32.000+03:00
* fix: render code blocks with unknown language as plain text

- CodeMirror descriptor no longer restricts to configured languages, so
  unknown languages fall back to a plain-text editor instead of crashing
- Inject unknown language as a temporary Select item so the dropdown
  reflects the current value
- Normalize null language/meta to '' in MdastCodeVisitor so the declared
  string type holds at runtime (fixes the no-language code block case)
- Handle empty-string canonical in array format of normalizeCodeBlockLanguages
  via EMPTY_VALUE sentinel (mirrors record format); enables a "Plain text"
  entry with alias: ['']
- Add CodeMirrorUnknownLanguage Ladle example demonstrating the behavior
- Add unit tests for unknown language lookups and empty canonical mapping

* fix: keep code block language selectors in sync

---------

Co-authored-by: Petyo Ivanov &lt;underlog@gmail.com&gt;
diff --git a/docs/code-blocks.md b/docs/code-blocks.md
@@ -123,7 +123,9 @@ codeMirrorPlugin({
 })
 ```
 
-With the array format, all aliases and extensions are recognized when matching code blocks, but the language select dropdown shows only one entry per language. This is especially useful when your markdown may use different identifiers for the same language (e.g. `js` vs `javascript`).
+With the array format, all aliases and extensions are recognized when resolving code block languages, but the language select dropdown shows only one entry per language. This is especially useful when your markdown may use different identifiers for the same language (e.g. `js` vs `javascript`).
+
+If a fenced code block has no `meta`, the CodeMirror editor acts as the default editor even when its language is not listed in `codeBlockLanguages`. In that case, the block falls back to plain-text editing and the unknown language is shown as a temporary item in the language picker so the user can keep it or switch to a configured language.
 
 You can also pass the `languages` array from `@codemirror/language-data` directly to support all CodeMirror languages:
 
diff --git a/src/examples/codemirror-languages.tsx b/src/examples/codemirror-languages.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import { MDXEditor, codeBlockPlugin, codeMirrorPlugin } from '../'
+import { ChangeCodeMirrorLanguage, ConditionalContents, MDXEditor, codeBlockPlugin, codeMirrorPlugin, toolbarPlugin } from '../'
 import { languages } from '@codemirror/language-data'
 import { markdown } from '@codemirror/lang-markdown'
 import { EditorView, keymap } from '@codemirror/view'
@@ -62,6 +62,21 @@ Markdown support is loaded:
 \`\`\`
 `
 
+function codeBlockLanguageToolbar() {
+  return toolbarPlugin({
+    toolbarContents: () => (
+      <ConditionalContents
+        options={[
+          { when: (editor) => editor?.editorType === 'codeblock', contents: () => <ChangeCodeMirrorLanguage /> },
+          {
+            fallback: () => <span>Focus a code block to edit its language from the toolbar.</span>
+          }
+        ]}
+      />
+    )
+  })
+}
+
 /**
  * Uses the CodeMirror `languages` array directly from `@codemirror/language-data`.
  * All aliases and extensions are recognized in the language select.
@@ -72,6 +87,7 @@ export function CodeMirrorLanguageData() {
       onChange={console.log}
       markdown={aliasSampleMarkdown}
       plugins={[
+        codeBlockLanguageToolbar(),
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: languages
@@ -91,6 +107,7 @@ export function CodeMirrorLanguageArray() {
       onChange={console.log}
       markdown={aliasSampleMarkdown}
       plugins={[
+        codeBlockLanguageToolbar(),
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: [
@@ -112,6 +129,7 @@ export function CodeMirrorLanguageWithSupport() {
       onChange={console.log}
       markdown={supportSampleMarkdown}
       plugins={[
+        codeBlockLanguageToolbar(),
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: [
@@ -136,6 +154,7 @@ export function CodeMirrorExtensions() {
       onChange={console.log}
       markdown={simpleSampleMarkdown}
       plugins={[
+        codeBlockLanguageToolbar(),
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: { js: 'JavaScript', ts: 'TypeScript' },
@@ -154,6 +173,50 @@ export function CodeMirrorExtensions() {
   )
 }
 
+const unknownLanguageSampleMarkdown = `
+Known \`js\` language:
+
+\`\`\`js
+const x = 1
+\`\`\`
+
+Unknown \`brainfuck\` language (rendered as plain text, no crash):
+
+\`\`\`brainfuck
+++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.
+\`\`\`
+
+No language at all:
+
+\`\`\`
+plain content
+\`\`\`
+`
+
+/**
+ * A code block whose language is not in the configured list falls back to a plain-text CodeMirror editor
+ * instead of crashing. The unknown language is shown as-is in the language select so the user can keep or change it.
+ */
+export function CodeMirrorUnknownLanguage() {
+  return (
+    <MDXEditor
+      onChange={console.log}
+      markdown={unknownLanguageSampleMarkdown}
+      plugins={[
+        codeBlockLanguageToolbar(),
+        codeBlockPlugin(),
+        codeMirrorPlugin({
+          codeBlockLanguages: [
+            { name: 'Plain text', alias: [''] },
+            { name: 'JavaScript', alias: ['js', 'javascript'] }
+          ],
+          autoLoadLanguageSupport: false
+        })
+      ]}
+    />
+  )
+}
+
 /**
  * Uses the legacy `Record<string, string>` format. Still works as before.
  */
@@ -163,6 +226,7 @@ export function CodeMirrorLanguageRecord() {
       onChange={console.log}
       markdown={aliasSampleMarkdown}
       plugins={[
+        codeBlockLanguageToolbar(),
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: { js: 'JavaScript', javascript: 'JavaScript', ts: 'TypeScript', typescript: 'TypeScript' }
diff --git a/src/plugins/codeblock/MdastCodeVisitor.ts b/src/plugins/codeblock/MdastCodeVisitor.ts
@@ -14,8 +14,8 @@ export const MdastCodeVisitor: MdastImportVisitor<Mdast.Code> = {
     actions.addAndStepInto(
       $createCodeBlockNode({
         code: mdastNode.value,
-        language: mdastNode.lang!,
-        meta: mdastNode.meta!
+        language: mdastNode.lang ?? '',
+        meta: mdastNode.meta ?? ''
       })
     )
   }
diff --git a/src/plugins/codemirror/CodeMirrorEditor.tsx b/src/plugins/codemirror/CodeMirrorEditor.tsx
@@ -12,7 +12,7 @@ import { indentWithTab } from '@codemirror/commands'
 import { basicLight } from 'cm6-theme-basic-light'
 import { basicSetup } from 'codemirror'
 import { $setSelection } from 'lexical'
-import { EMPTY_VALUE, codeBlockLanguages$, codeMirrorAutoLoadLanguageSupport$, codeMirrorExtensions$ } from '.'
+import { EMPTY_VALUE, codeBlockLanguages$, codeMirrorAutoLoadLanguageSupport$, codeMirrorExtensions$, getCodeBlockLanguageSelectData } from '.'
 import { useCodeMirrorRef } from '../sandpack/useCodeMirrorRef'
 import { Select } from '../toolbar/primitives/select'
 
@@ -34,6 +34,11 @@ export const CodeMirrorEditor = ({ language, nodeKey, code, focusEmitter }: Code
   const editorViewRef = React.useRef<EditorView | null>(null)
   const elRef = React.useRef<HTMLDivElement | null>(null)
 
+  const { value: selectValue, items: selectItems } = React.useMemo(
+    () => getCodeBlockLanguageSelectData(codeBlockLanguages, language),
+    [codeBlockLanguages, language]
+  )
+
   const setCodeRef = React.useRef(setCode)
   setCodeRef.current = setCode
   codeMirrorRef.current = {
@@ -104,7 +109,7 @@ export const CodeMirrorEditor = ({ language, nodeKey, code, focusEmitter }: Code
       <div className={styles.codeMirrorToolbar}>
         <Select
           disabled={readOnly}
-          value={codeBlockLanguages.keyMap[language] ?? language}
+          value={selectValue}
           onChange={(language) => {
             parentEditor.update(() => {
               lexicalNode.setLanguage(language === EMPTY_VALUE ? '' : language)
@@ -117,7 +122,7 @@ export const CodeMirrorEditor = ({ language, nodeKey, code, focusEmitter }: Code
           }}
           triggerTitle={t('codeBlock.selectLanguage', 'Select code block language')}
           placeholder={t('codeBlock.inlineLanguage', 'Language')}
-          items={codeBlockLanguages.items}
+          items={selectItems}
         />
         <button
           className={styles.iconButton}
diff --git a/src/plugins/codemirror/index.tsx b/src/plugins/codemirror/index.tsx
@@ -57,10 +57,13 @@ export function normalizeCodeBlockLanguages(input: Record<string, string> | Code
 
   if (Array.isArray(input)) {
     for (const lang of input) {
-      // The canonical key is the first alias, or the lowercased name
-      const canonical = lang.alias?.[0] ?? lang.name.toLowerCase()
+      // The canonical key is the first alias, or the lowercased name.
+      // Empty string canonical (e.g. Plain text with alias: ['']) is stored as EMPTY_VALUE
+      // because Radix Select does not accept items with an empty string value.
+      const rawCanonical = lang.alias?.[0] ?? lang.name.toLowerCase()
+      const canonical = rawCanonical || EMPTY_VALUE
       items.push({ value: canonical, label: lang.name })
-      keyMap[canonical] = canonical
+      keyMap[rawCanonical] = canonical
       if (lang.alias) {
         for (const alias of lang.alias) {
           keyMap[alias] = canonical
@@ -91,6 +94,25 @@ export function normalizeCodeBlockLanguages(input: Record<string, string> | Code
   return { items, keyMap, supportMap }
 }
 
+/**
+ * Resolves the current language to the select value and items used by CodeMirror language pickers.
+ * Unknown languages are added as a temporary item so the picker remains in sync with the code block value.
+ */
+export function getCodeBlockLanguageSelectData(
+  normalized: NormalizedCodeBlockLanguages,
+  language: string
+): { value: string; items: { value: string; label: string }[] } {
+  const value = normalized.keyMap[language] ?? language
+  if (!value || normalized.items.some((item) => item.value === value)) {
+    return { value, items: normalized.items }
+  }
+
+  return {
+    value,
+    items: [...normalized.items, { value, label: language }]
+  }
+}
+
 /**
  * The normalized code block languages used by the CodeMirror editor.
  * @group CodeMirror
@@ -180,10 +202,10 @@ export const codeMirrorPlugin = realmPlugin<{
   }
 })
 
-function buildCodeBlockDescriptor(normalized: NormalizedCodeBlockLanguages): CodeBlockEditorDescriptor {
+function buildCodeBlockDescriptor(_normalized: NormalizedCodeBlockLanguages): CodeBlockEditorDescriptor {
   return {
-    match(language, meta) {
-      return Object.hasOwn(normalized.keyMap, language ?? '') && !meta
+    match(_language, meta) {
+      return !meta
     },
     priority: 1,
     Editor: CodeMirrorEditor
diff --git a/src/plugins/toolbar/components/ChangeCodeMirrorLanguage.tsx b/src/plugins/toolbar/components/ChangeCodeMirrorLanguage.tsx
@@ -2,7 +2,7 @@ import { useCellValues } from '@mdxeditor/gurx'
 import React from 'react'
 import styles from '../../../styles/ui.module.css'
 import { $isCodeBlockNode } from '../../codeblock/CodeBlockNode'
-import { EMPTY_VALUE, codeBlockLanguages$ } from '../../codemirror'
+import { EMPTY_VALUE, codeBlockLanguages$, getCodeBlockLanguageSelectData } from '../../codemirror'
 import { activeEditor$, editorInFocus$, useTranslation } from '../../core'
 import { Select } from '.././primitives/select'
 
@@ -22,15 +22,12 @@ export const ChangeCodeMirrorLanguage = () => {
   }
 
   const rawLanguage = codeBlockNode.getLanguage()
-  let currentLanguage = codeBlockLanguages.keyMap[rawLanguage] ?? rawLanguage
-  if (currentLanguage === '') {
-    currentLanguage = EMPTY_VALUE
-  }
+  const { value: currentLanguage, items } = getCodeBlockLanguageSelectData(codeBlockLanguages, rawLanguage)
   return (
     <div className={styles.selectWithLabel}>
       <label>{t('codeBlock.language', 'Code block language')}</label>
       <Select
-        value={currentLanguage}
+        value={currentLanguage || EMPTY_VALUE}
         onChange={(language) => {
           theEditor?.update(() => {
             codeBlockNode.setLanguage(language === EMPTY_VALUE ? '' : language)
@@ -43,7 +40,7 @@ export const ChangeCodeMirrorLanguage = () => {
         }}
         triggerTitle={t('codeBlock.selectLanguage', 'Select code block language')}
         placeholder={t('codeBlock.language', 'Code block language')}
-        items={codeBlockLanguages.items}
+        items={items}
       />
     </div>
   )
diff --git a/src/test/codemirror.test.ts b/src/test/codemirror.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { normalizeCodeBlockLanguages, EMPTY_VALUE, type CodeBlockLanguageSupport } from '../plugins/codemirror'
+import { getCodeBlockLanguageSelectData, normalizeCodeBlockLanguages, EMPTY_VALUE, type CodeBlockLanguageSupport } from '../plugins/codemirror'
 
 describe('normalizeCodeBlockLanguages', () => {
   describe('record format', () => {
@@ -68,6 +68,18 @@ describe('normalizeCodeBlockLanguages', () => {
       const result = normalizeCodeBlockLanguages([{ name: 'JavaScript', alias: ['js'] }])
       expect(result.keyMap.javascript).toBe('js')
     })
+
+    it('maps empty-string canonical to EMPTY_VALUE sentinel', () => {
+      const result = normalizeCodeBlockLanguages([
+        { name: 'Plain text', alias: [''] },
+        { name: 'JavaScript', alias: ['js'] }
+      ])
+      expect(result.items).toEqual([
+        { value: EMPTY_VALUE, label: 'Plain text' },
+        { value: 'js', label: 'JavaScript' }
+      ])
+      expect(result.keyMap['']).toBe(EMPTY_VALUE)
+    })
   })
 
   describe('supportMap', () => {
@@ -107,4 +119,58 @@ describe('normalizeCodeBlockLanguages', () => {
       expect(result.keyMap).toEqual({})
     })
   })
+
+  describe('unknown language', () => {
+    it('returns undefined from keyMap for an unknown language (record format)', () => {
+      const result = normalizeCodeBlockLanguages({ js: 'JavaScript' })
+      expect(result.keyMap.brainfuck).toBeUndefined()
+      expect(Object.hasOwn(result.keyMap, 'brainfuck')).toBe(false)
+    })
+
+    it('returns undefined from keyMap for an unknown language (array format)', () => {
+      const result = normalizeCodeBlockLanguages([{ name: 'JavaScript', alias: ['js'], extensions: ['js', 'mjs'] }])
+      expect(result.keyMap.brainfuck).toBeUndefined()
+      expect(Object.hasOwn(result.keyMap, 'brainfuck')).toBe(false)
+    })
+
+    it('returns undefined from supportMap for an unknown language', () => {
+      const mockSupport: CodeBlockLanguageSupport = { extension: [] }
+      const result = normalizeCodeBlockLanguages([{ name: 'JavaScript', alias: ['js'], support: mockSupport }])
+      expect(result.supportMap.brainfuck).toBeUndefined()
+    })
+
+    it('does not include an unknown language in items', () => {
+      const result = normalizeCodeBlockLanguages([{ name: 'JavaScript', alias: ['js'] }])
+      expect(result.items.find((item) => item.value === 'brainfuck')).toBeUndefined()
+    })
+  })
+})
+
+describe('getCodeBlockLanguageSelectData', () => {
+  it('returns configured items for a known language', () => {
+    const normalized = normalizeCodeBlockLanguages([{ name: 'JavaScript', alias: ['js'] }])
+    expect(getCodeBlockLanguageSelectData(normalized, 'js')).toEqual({
+      value: 'js',
+      items: [{ value: 'js', label: 'JavaScript' }]
+    })
+  })
+
+  it('adds a temporary item for an unknown language', () => {
+    const normalized = normalizeCodeBlockLanguages([{ name: 'JavaScript', alias: ['js'] }])
+    expect(getCodeBlockLanguageSelectData(normalized, 'brainfuck')).toEqual({
+      value: 'brainfuck',
+      items: [
+        { value: 'js', label: 'JavaScript' },
+        { value: 'brainfuck', label: 'brainfuck' }
+      ]
+    })
+  })
+
+  it('keeps the empty-language sentinel intact', () => {
+    const normalized = normalizeCodeBlockLanguages([{ name: 'Plain text', alias: [''] }])
+    expect(getCodeBlockLanguageSelectData(normalized, '')).toEqual({
+      value: EMPTY_VALUE,
+      items: [{ value: EMPTY_VALUE, label: 'Plain text' }]
+    })
+  })
 })

Original file line number	Diff line number	Diff line change
`@@ -14,8 +14,8 @@ export const MdastCodeVisitor: MdastImportVisitor<Mdast.Code> = {`
`14`	`14`	`actions.addAndStepInto(`
`15`	`15`	`$createCodeBlockNode({`
`16`	`16`	`code: mdastNode.value,`
`17`		`- language: mdastNode.lang!,`
`18`		`- meta: mdastNode.meta!`
	`17`	`+ language: mdastNode.lang ?? '',`
	`18`	`+ meta: mdastNode.meta ?? ''`
`19`	`19`	`})`
`20`	`20`	`)`
`21`	`21`	`}`