CKEditor 5 code block: preserve editable code and its language on save

An original service-desk article contains a small HTML status badge and a paragraph explaining where to place it. The author needs to preserve the badge's literal tags and indentation, change its language label, and continue typing outside the block. Rendering the badge as an HTML embed would produce a different result.

Add the feature to the existing editor

In a current npm-based CKEditor setup, import CodeBlock from ckeditor5, include it in the existing plugins array, and add codeBlock to the toolbar. Keep the application's other required plugins and valid license configuration.

Merge this configuration into that initialization:

const serviceArticleCodeOptions = {
  codeBlock: {
    languages: [
      { language: 'plaintext', label: 'Plain text', class: '' },
      { language: 'html', label: 'HTML' },
      { language: 'css', label: 'CSS' }
    ],
    indentSequence: '  '
  }
};

This object is a configuration fragment, not an editor installation. Its first language is the default for newly inserted blocks and loaded blocks without a matching class. Including Plain text first makes that fallback deliberate instead of labeling unidentified text as HTML.

indentSequence uses two spaces for this article's samples. It changes the indentation operation; it does not prove that a copied snippet follows a project's formatting rules.

Insert literal code instead of a rendered widget

Use the toolbar to create an HTML code block, then enter this original fixture as text:

<span class="service-status">
  Awaiting replacement sensor
</span>

The author should see the tags in an editable code block. In serialized HTML, expect the code text to be escaped within a structure such as:

<pre><code class="language-html">&lt;span class="service-status"&gt;
  Awaiting replacement sensor
&lt;/span&gt;</code></pre>

Check the literal characters, line breaks, and language rather than demanding identical whitespace in every serialized wrapper. HTML code and pre explains the reader markup. CKEditor HTML embed instead treats a fragment as an embedded widget; use that when the rendered badge is the intended content.

Change the language without toggling the block off

The ordinary command can create a block or convert selected content:

editor.execute('codeBlock', { language: 'html' });

Here editor is an initialized instance with the feature installed. At a selection already inside a code block, the command normally toggles the block back to paragraphs. To change that existing block's language explicitly, use the documented force option:

editor.execute('codeBlock', {
  language: 'css',
  forceValue: true
});

Only use configured language identifiers. Changing the label does not translate HTML into CSS or validate the code. For the badge fixture, restore HTML before saving the final article.

Continue the article and verify the round trip

At the end of the last line, press Enter three times to create a paragraph after the code block. The official guide also explains creating a paragraph before a block when the caret has no obvious surrounding paragraph. Confirm that the explanatory sentence lands outside the code.

Use Tab and Shift+Tab on the intended code lines and check the two-space indentation behavior. Then save and reopen through the application's real storage path. Confirm that the badge remains literal text with the HTML language class and that the explanatory paragraph remains separately editable.

For reader-side color, integrate a highlighter with language classes that match this configuration. The highlight.js guide covers display highlighting. Keep that reader transformation separate from the editable record, and finish by copying the badge from the published-preview code block: the recipient should receive the literal snippet, without generated line numbers or a rendered span.