Code Blocks

Code blocks are a simple way to display formatted code with syntax highlighting.

Code blocks by default are a simple way to display code. But, BlockNote also supports more advanced features like:

• Syntax highlighting
• Custom themes
• Multiple languages
• Tab indentation

Configuration Options

type CodeBlockOptions = {
  indentLineWithTab?: boolean;
  defaultLanguage?: string;
  supportedLanguages?: Record<
    string,
    {
      name: string;
      aliases?: string[];
    }
  >;
};

indentLineWithTab: Whether the Tab key should indent lines, or not be handled by the code block specially. Defaults to true.

defaultLanguage: The syntax highlighting default language for code blocks which are created/inserted without a set language, which is text by default (no syntax highlighting).

supportedLanguages: The syntax highlighting languages supported by the code block, which is an empty array by default.

Syntax Highlighting

Syntax highlighting is handled by a separate editor extension that you add to the editor's extensions (not configured on the code block itself), so it can highlight any block that declares a language — the code block, and blocks like the math block. When the extension isn't added, those blocks render as plain text.

The extension is configured with a Shiki highlighter:

type SyntaxHighlightingOptions = {
  createHighlighter: () => Promise<HighlighterGeneric<any, any>>;
};

createHighlighter: The Shiki highlighter to use for syntax highlighting.

Which blocks get highlighted (and as which language) is decided by each block's spec via its meta.highlight callback — the code block highlights as its language prop, the math block always as latex — so you don't configure this on the extension.

BlockNote provides a generic, ready-to-use highlighter in the @blocknote/code-block package, which supports a wide range of languages. It's exported as a pre-configured syntaxHighlighter extension, alongside the code block options:

import { createCodeBlockSpec } from "@blocknote/core";
import { codeBlockOptions, syntaxHighlighter } from "@blocknote/code-block";

const editor = useCreateBlockNote({
  extensions: [syntaxHighlighter],
  schema: BlockNoteSchema.create().extend({
    blockSpecs: {
      codeBlock: createCodeBlockSpec(codeBlockOptions),
    },
  }),
});

See this example to see it in action.

Type & Props

type CodeBlock = {
  id: string;
  type: "codeBlock";
  props: {
    language: string;
  };
  content: InlineContent[];
  children: Block[];
};

language: The syntax highlighting language to use. Defaults to text, which has no highlighting.

Custom Syntax Highlighting

To create your own syntax highlighter, you can use the shiki-codegen CLI for generating the code to create one for your chosen languages and themes.

For example, to create a syntax highlighter using the optimized javascript engine, javascript, typescript, vue, with light and dark themes, you can run the following command:

npx shiki-codegen --langs javascript,typescript,vue --themes light-plus,dark-plus --engine javascript --precompiled ./shiki.bundle.ts

This will generate a shiki.bundle.ts file that you can use to create a syntax highlighter for your editor.

Like this:

import { SyntaxHighlightingExtension } from "@blocknote/core";
import { createHighlighter } from "./shiki.bundle.js";

// Build a syntax highlighter extension from your custom Shiki bundle, then add
// it to the editor's `extensions`.
const syntaxHighlighter = SyntaxHighlightingExtension({
  createHighlighter: () =>
    createHighlighter({
      themes: ["light-plus", "dark-plus"],
      langs: [],
    }),
});

export default function App() {
  const editor = useCreateBlockNote({
    extensions: [syntaxHighlighter],
    schema: BlockNoteSchema.create().extend({
      blockSpecs: {
        codeBlock: createCodeBlockSpec({
          indentLineWithTab: true,
          defaultLanguage: "typescript",
          supportedLanguages: {
            typescript: {
              name: "TypeScript",
              aliases: ["ts"],
            },
          },
        }),
      },
    }),
  });

  return <BlockNoteView editor={editor} />;
}

See the custom code block example for a more detailed example.