Syntax guide

Elastic Docs V3 uses Markdown as its main content authoring format.

V3 fully supports CommonMark, a strongly defined, standard-compliant Markdown specification. In many cases, plain Markdown syntax will be sufficient when authoring Elastic content. On top of this functionality, there are two main syntax extension points:

• Directives
• GitHub-flavored markdown

The following directives are available in Elastic Docs V3:

• Admonitions - Callouts and warnings
• Code blocks - Syntax-highlighted code
• CSV include - Render CSV files as tables
• Diagrams - Visual diagrams and charts
• Dropdowns - Collapsible content
• Images - Enhanced image handling
• Include - Include content from other files
• Settings - Configuration blocks
• Stepper - Step-by-step content
• Tabs - Tabbed content organization
• Tables - Data tables
• Version blocks - API version information

Directives extend CommonMark functionality. Directives have the following syntax:

:::{EXTENSION} ARGUMENTS
:OPTION: VALUE

Nested content that will be parsed as markdown
:::
		

• EXTENSION is the name of the directive. Names are always wrapped in brackets { }. For example: {note}.
• ARGUMENT an optional main argument. For example: :::{include} _snippets/include.md :::
• :OPTION: VALUE is used to further customize a given directive.

Defining directives with ::: allows the nested markdown syntax to be highlighted properly by editors and web viewers.

Increase the number of leading semicolons to include nested directives.

In the following example, a {note} wraps a {hint}:

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

All directive are indicated with semicolons except literal blocks. For these you need to use triple backticks.

• Code blocks
• {applies-to} blocks

Since their contents should not be parsed as markdown they use backticks. This also ensures maximum interopability with existing markdown editors and previews.

Many Markdown editors support syntax highlighting for embedded code blocks. For compatibility with this feature, use triple backticks instead of triple colons for content that needs to be displayed literally:

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

We support some GitHub Flavored Markdown (GFM) extensions.

• Tables > Basic Table
• Strikethrough: as seen here

• Task lists
• Auto links (http://www.elastic.co)
• Using a subset of HTML