A feature that I love about docusaurus is that it uses Prism for syntax highlighting. With Prism, there is support for almost every language you can name. There is support for Power Query (M) and DAX thanks to Peter Budai. My current code samples are mainly in Javascript but I will be writing samples in DAX and Power Query so this is an important feature. Here is how I configured Docusaurus to support the additional languages and how to change themes.
Prism
To use Prism with Hugo I had to add it manually since it supported a different syntax highlighter. The reason I added Prism to Hugo was the built-in syntax highlighter did not support languages like Power Query (M) and DAX. This involved adding the necessary Javascript and CSS to the source code files. With Docusaurus it is ready to use for a handful of languages and easy to configure additional languages and themes.
Included languages
The languages included by default are listed here. These are the languages you can start using immediately without adding anything to the docusaurus configuration. Currently, that list includes languages like Javascript, C++, Bash, Python, and SQL. If you want to add a language such as C# that Prism supports but is not one of the default languages it is easy to add it to Docusaurus.
Adding Languages
Docusaurus supports syntax highlighting for all of the languages that Prism supports.
To add support for the additional languages you need to add the language under the prism configuration in the docusaurus.config.js file. For the proper name to add you need to make sure it matches a valid Prism component. To confirm you can check node_modules/prismjs/components for the name. For instance, if you want to add support for C# and you check that list of components you will see the file prism-csharp.js. You would add csharp to the array of additional languages. Here is an example of adding a couple of languages to the configuration file:
themeConfig:
(
...
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
additionalLanguages: ['dax', 'csharp', 'powerquery', 'powershell'],
},
}),
You do need to restart Docusaurus after adding additional languages. Remember that we are only adding languages that are not included by default. If you are working with a language that Prism does not support you can add the language but it will take more work.
Using it in Markdown
Code blocks start with 3 backticks and end with 3 backticks. When using the language name in a code block you may have a choice of multiple aliases for the language. You can check the component files and you may see the additional aliases listed near the bottom. For example, if you are writing a code block for Power Query you have the choice to use the language identifiers pq, mscript, or powerquery. If the language is C# it will accept dotnet, cs, or csharp.
Example code block for DAX with a title, line numbers, and line highlighting:
```dax title="DAX" {4,6} showLineNumbers
EVALUATE
SUMMARIZECOLUMNS (
'BUSegment'[BU Name],
'Date'[Year],
TREATAS ( { "2021", "2022" }, 'Date'[Year] ),
"Core EBITDA", [Core EBITDA],
"Actual Volume", [Actual Volume]
)
```
Use 4 backticks to start and end a section that you want to appear as is without parsing out the code block. The above sample code was done this way to show the 3 backticks and options like showLineNumbers.
What it looks like:
EVALUATE
SUMMARIZECOLUMNS (
'BUSegment'[BU Name],
'Date'[Year],
TREATAS ( { "2021", "2022" }, 'Date'[Year] ),
"Core EBITDA", [Core EBITDA],
"Actual Volume", [Actual Volume]
)
Example code block with a title and using magic comments (more on magic comments below):
```powerquery title="Power Query"
let
//highlight-next-line
Source = Csv.Document(File.Contents("\\Gallifrey\Budget.csv"),[Delimiter=",", Columns=13, Encoding=1252, QuoteStyle=QuoteStyle.None]),
#"Promoted Headers" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]),
// highlight-start
#"Removed Other Columns" = Table.SelectColumns(#"Promoted Headers",{"AccountingPeriodsId", "DepartmentsId", "AccountsId", "Amount", "ClassesId", "DateId", "Category"})
// highlight-end
in
#"Removed Other Columns"
What it looks like:
let
Source = Csv.Document(File.Contents("\\Gallifrey\Budget.csv"),[Delimiter=",", Columns=13, Encoding=1252, QuoteStyle=QuoteStyle.None]),
#"Promoted Headers" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]),
#"Removed Other Columns" = Table.SelectColumns(#"Promoted Headers",{"AccountingPeriodsId", "DepartmentsId", "AccountsId", "Amount", "ClassesId", "DateId", "Category"})
in
#"Removed Other Columns"
Magic comments allow you to highlight code within the code block without having to deal with counting lines or adjusting the line number if you add or remove code. The comments are removed and replaced with the indicated highlighting. Note that you cannot use magic comments and specify a range to be highlighted i.e. {3-4}. There are various options that you can add to each code block and instructions on using CSS to change the highlighting background color.
Themes
Prism in Docusaurus supports various themes for how your code blocks look. In the default docusaurus.config.js file it has two lines near the top that define two constants - one for the light theme and one for the dark theme. These are then used in the prism configuration further down in the file (the same place we configure additional languages).
Currently, the list of themes is dracula, duotoneDark, duotoneLight, github, nightOwl, nightOwlLight, oceanNext, okaidia, palenight, ShadesofPurple, synthwave84, ultramin, vsDark, and vsLight. You can find the list in node_modules\prism-react-renderer\themes.
const lightCodeTheme = require('prism-react-renderer/themes/vsDark');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
...
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
additionalLanguages: ['dax', 'csharp', 'powerquery', 'powershell'],
},
By swapping out the values in the require statement you can try out the various themes. Make sure you try both the light and dark modes on the site to see what it looks like. Also, you should include line highlighting in your sample so you can see what it looks like with a different theme. If you want to change the background color for the line highlighting you will need to modify the CSS.
Highlights
Docusaurus includes syntax highlighting for commonly used languages. If you require additional languages it takes minimal configuring to add those languages. Themes allow you to customize the code blocks to look the way you want. When I was evaluating Docusaurus a major benefit was that Prism syntax highlighting was included. You can enhance code blocks to add multiple-language support using tabs or having an interactive code editor. Docusaurus allows you to get your site up quickly and then explore all that it offers to customize your site just the way you want.