Markdown Syntax Extensions

Syntax¶

The new documentation fully supports CommonMark Markdown syntax.

On top of this widely accepted feature set we have various extensions points.

Directives are our main extension point over markdown and follows the following syntax

		:::{EXTENSION} ARGUMENTS
:OPTION: VALUE

Nested content that will be parsed as markdown
:::

EXTENSION is the name of the directive e.g note
ARGUMENT some directives take a main argumnt e.g :::{include} _snippets/include.md
OPTION and VALUE can be used to further customize a given directive.

The usage of ::: allows the nested markdown to be syntax highlighted properly by editors and web viewers.

Our (directives) are always wrapped in brackets { }.

You can increase the leading semicolons to include nested directives. Here the {note} wraps a {hint}.

		::::{note} My note
:::{hint} My hint
Content displayed in the hint admonition
:::
Content displayed in the note admonition
::::

	

For best editor compatability it is recommended to use triple backticks for content that needs to be displayed literally

		```js
const x = 1;
```

	

Many markdown editors support syntax highlighting for embedded code blocks.

We support some of GitHub flavor markdown extensions these are highlighted in green here: https://github.github.com/gfm/

Supported:

Not supported: