{@snippet features/build-code-block-source}
The {@link module:code-block/codeblock~CodeBlock} feature allows inserting and editing blocks of pre–formatted code into the editor. Code blocks have their specific languages (e.g. "Java" or "CSS") and support basic editing tools, for instance, changing the line indentation using the keyboard.
{@snippet features/code-block}
Each code block can have its language. The language of the code block is represented as a CSS class of the <code> element, both when editing and in the editor data:
<pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
It is possible to configure which languages are available. You can use the {@link module:code-block/codeblock~CodeBlockConfig#languages codeBlock.languages} configuration and define your own languages. For example, the following editor supports only two languages (CSS and XML/HTML):
ClassicEditor
.create( document.querySelector( '#editor' ), {
codeBlock: {
languages: [
{ language: 'css', label: 'CSS' },
{ language: 'xml', label: 'HTML/XML' }
]
}
} )
.then( ... )
.catch( ... );
{@snippet features/code-block-custom-languages}
By default, the CSS class of the <code> element in data and editing is generated using the language property (prefixed with "language-"). You can customize it by specifying an optional class property:
ClassicEditor
.create( document.querySelector( '#editor' ), {
codeBlock: {
languages: [
// Do not render the CSS class for the plain text code blocks.
{ language: 'plaintext', label: 'Plain text', class: '' },
// Use the "php-code" class for PHP code blocks.
{ language: 'php', label: 'PHP', class: 'php-code' },
// Use the "js" class for JavaScript code blocks.
{ language: 'javascript', label: 'JavaScript', class: 'js' },
// Python code blocks will have the default "language-python" CSS class.
{ language: 'python', label: 'Python' }
]
}
} )
.then( ... )
.catch( ... );
The first language defined in the configuration is considered the default one. This means it will be applied to code blocks loaded from data that have no CSS `class` specified (or no `class` matching the {@link module:code-block/codeblock~CodeBlockConfig#languages configuration}). It will also be used when creating new code blocks using the toolbar button. By default it is "Plain text" (`language-plaintext` CSS class).
Although the live code block highlighting is impossible when editing in CKEditor 5 (learn more), the content can be highlighted when displayed in the frontend (e.g. in blog posts, messages, etc.).
The code language {@link module:code-block/codeblock~CodeBlockConfig#languages configuration} helps to integrate with external code highlighters (e.g. highlight.js or Prism). Please refer to the documentation of the highlighter of your choice and make sure CSS classes configured in codeBlock.languages correspond with the code syntax auto–detection feature of the highlighter.
There could be situations when there is no obvious way to set the caret before or after a block of code and type. This can happen when the code block is preceded or followed by a widget (e.g. a table) or when the code block is the first or the last child of the document (or both).
{@img assets/img/typing-before.gif 770 The animation shows typing before the code blocks in CKEditor 5 rich text editor.}
{@img assets/img/typing-after.gif 770 The animation shows typing after the code blocks in CKEditor 5 rich text editor.}
You can change the indentation of the code using keyboard shortcuts and toolbar buttons:
{@img assets/img/outdent-indent.gif 770 The animation shows changing indention inside code blocks in CKEditor 5 rich text editor.}
The indentation created this way can be changed. Use the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`} configuration to choose some other character (or characters) of your preference (e.g. four spaces). By default, the indentation changes by a single tab (`\t`) character.
You can disable the indentation tools and their associated keystrokes altogether by setting the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`} configuration `false`.
To speed up the editing, when typing in a code block, the indentation of the current line is preserved when you hit Enter and create a new line. If you want to change the indentation of the new line, take a look at some easy ways to do that.
{@img assets/img/preserve-indention.gif 770 The animation shows preserving indention inside code blocks in CKEditor 5 rich text editor.}
To add this feature to your editor install the @ckeditor/ckeditor5-code-block package:
npm install --save @ckeditor/ckeditor5-code-block
And add it to your plugin list and the toolbar configuration:
import CodeBlock from '@ckeditor/ckeditor5-code-block/src/codeblock';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ CodeBlock, ... ],
toolbar: [ 'codeBlock', ... ]
} )
.then( ... )
.catch( ... );
Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
The {@link module:code-block/codeblock~CodeBlock} plugin registers:
'codeBlock' split button with a dropdown allowing to choose the language of the block,The {@link module:code-block/codeblockcommand~CodeBlockCommand 'codeBlock'} command.
The command converts selected editor content into a code block. If no content is selected, it creates a new code block at the place of the selection.
You can choose which language the code block is written in when executing the command. The language will be set in the editor model and reflected as a CSS class visible in the editing view and the editor (data) output:
editor.execute( 'codeBlock', { language: 'css' } );
When executing the command, you can use languages defined by the {@link module:code-block/codeblock~CodeBlockConfig#languages codeBlock.languages} configuration. The default list of languages is as follows:
codeBlock.languages: [
{ language: 'plaintext', label: 'Plain text' }, // The default language.
{ language: 'c', label: 'C' },
{ language: 'cs', label: 'C#' },
{ language: 'cpp', label: 'C++' },
{ language: 'css', label: 'CSS' },
{ language: 'diff', label: 'Diff' },
{ language: 'xml', label: 'HTML/XML' },
{ language: 'java', label: 'Java' },
{ language: 'javascript', label: 'JavaScript' },
{ language: 'php', label: 'PHP' },
{ language: 'python', label: 'Python' },
{ language: 'ruby', label: 'Ruby' },
{ language: 'typescript', label: 'TypeScript' },
]
Note: If you execute a command with a specific language when the selection is anchored in a code block and use the additional forceValue: true parameter, it will update the language of this particular block.
editor.execute( 'codeBlock', { language: 'java', forceValue: true } );
Note: If the selection is already in a code block, executing the command will convert the block back into plain paragraphs.
The {@link module:code-block/indentcodeblockcommand~IndentCodeBlockCommand 'indentCodeBlock'} and {@link module:code-block/outdentcodeblockcommand~OutdentCodeBlockCommand 'outdentCodeBlock'} commands.
Both commands are used by the Tab and Shift+Tab keystrokes as described in one of the chapters:
codeBlock.indentSequence} configuration.codeBlock.indentSequence}.
We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-code-block.