Code blocks within documentation are super-powered 💪.
You can add a title to the code block by adding
title key after the language (leave a space between them).
Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out this reference for specifications of MDX.
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by Prism React Renderer.
For example, if you prefer to use the
dracula highlighting theme:
By default, Docusaurus comes with this subset of commonly used languages.
To add syntax highlighting for any of the other Prism supported languages, define it in an array of additional languages.
For example, if you want to add highlighting for the
If you want to add highlighting for languages not yet supported by Prism, you can swizzle
It will produce
prism-include-languages.js in your
src/theme folder. You can add highlighting support for custom languages by editing
You can refer to Prism's official language definitions when you are writing your own language definitions.
You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
To accomplish this, Docusaurus adds the
docusaurus-highlight-code-line class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your
src/css/custom.css with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the
parse-number-range library and you can find more syntax on their project details.
You can also use comments with
highlight-end to select which lines are highlighted.
Supported commenting syntax:
If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
(Powered by React Live)
You can create an interactive coding editor with the
First, add the plugin to your package.
You will also need to add the plugin to your
To use the plugin, create a code block with
live attached to the language meta string.
The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.
It is 1:20:25 PM.
react-live and imports
It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.
By default, all React imports are available. If you need more imports available, swizzle the react-live scope:
ButtonExample component is now available to use:
With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.
Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a generic Tabs component in the classic theme so that you can use it for other non-code scenarios as well.
The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block is intentional. This is a current limitation of MDX, you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not JSX.
And you will get the following:
You may want to implement your own
<MultiLanguageCode /> abstraction if you find the above approach too verbose. We might just implement one in future for convenience.
If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the Syncing tab choices section.