Syntax quick reference

This page offers quick guidance on Elastic Docs v3 syntax, including usage tips. Elements are in alphabetical order. The full syntax guide provides implementation details.

Use admonitions to caution users, or to provide helpful tips or extra information.

:::{warning}
Users could permanently lose data or leak sensitive information.
:::

:::{important}
Less dire than a warning. Users might encounter issues with performance or stability.
:::

:::{note}
Supplemental information that provides context or clarification.
:::

:::{tip}
Advice that helps users work more efficiently or make better choices.
:::

:::{admonition} Special note
Custom admonition with custom label.
:::

DOs
✅ Use custom admonitions as needed

DON'Ts
❌ Stack admonitions
❌ Overload a page with too many admonitions

A default anchor is automatically created for each heading, in the form #heading-text (hyphenated, lowercase, special characters and spaces trimmed). To create a custom anchor, add it in square brackets at the end of a heading: [my-better-anchor]

#### Hello world!
<!-- Auto-generated default anchor: #hello-world -->

#### Hello world! [get-started]

DOs
✅ Create custom anchors for repeated structural headings like "Example request"

DON'Ts
❌ Include punctuation marks in custom anchors
❌ Define custom anchors in text that is not a heading

More details: Links →

Tags that identify technical contexts: the feature base (stack/serverless), deployments, and project types that a piece of content "applies to." Use applies_to tags to help users determine whether content is right for their deployments and configuration. These tags are a version content pattern in Elastic Docs v3.

Example: Section tag

# Stack-only content
```{applies_to}
stack:
```

For full syntax and more examples, see Applies to.

DOs
✅ Define a set of page-level tags in a front matter block
✅ Add section-level tags in an {applies_to} directive after a heading
✅ Indicate versions (major.minor with an optional [.patch]) and release phases like beta

DON'Ts
❌ Include applies_to tags in admonitions
❌ Add applies_to tags to general, broadly applicable content
❌ Use Coming (x.x.x) tags, except in special cases (don't pre-announce features)

Multi-line blocks for code, commands, configuration, and similar content. Use three backticks ``` on separate lines to start and end the block. For syntax highlighting, add a language identifier after the opening backticks.

```yaml
server.host: "0.0.0.0"
elasticsearch.hosts: ["http://localhost:9200"]
```

server.host: "0.0.0.0"
elasticsearch.hosts: ["http://localhost:9200"]

DOs
✅ Include code blocks within lists or other block elements as needed
✅ Add language identifiers like yaml, json, bash

DON'Ts
❌ Place code blocks in admonitions
❌ Use inline code formatting (single backticks) for multi-line content

More details: Code →

Inline annotations that highlight or explain specific lines in a code block.

To explicitly create a code callout, add a number marker in angle brackets (<1>, <2>, ...) at the end of a line. Add the corresponding callout text below the code block, in a numbered list that matches the markers.

```json
{
  "match": {
    "message": "search text" <1>
  }
}
```
1. Searches the `message` field for the phrase "search text"

{
  "match": {
    "message": "search text"
  }
}

Add comments with // or # to magically create callouts.

```json
{
  "match": {
    "message": "search text" // Searches the message field
  }
}
```

{
  "match": {
    "message": "search text"
  }
}

DOs
✅ Keep callout text short and specific
✅ Use only one type of callout per code block (don't mix explicit and magic)
✅ Make sure there's a corresponding list item for each explicit callout marker in a code block

DON'Ts
❌ Overuse callouts -- they can impede readability

More details: Code callouts→

Use % to add single-line comments. Use HTML-style <!-- and --> for multi-line comments.

% This is a comment
This is regular text

<!--
so much depends
upon
a multi-line
comment
-->
Regular text after multi-line comment

DOs
✅ Add a space after % to start a single-line comment

DON'Ts
❌ Use # or // for comments; they're reserved for magic callouts

Collapsible blocks for hiding and showing content.

:::{dropdown} Title or label
Collapsible content
:::

DOs
✅ Use dropdowns for text, lists, images, code blocks, and tables
✅ Add :open: to auto-expand a dropdown by default

DON'Ts
❌ Use dropdowns for very long paragraphs or entire sections

More details: Dropdowns →

Title of a page or a section. To create a heading, add number signs # at the beginning of the line (one # for each heading level).

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Output

×

DOs
✅ Start every page with a Heading 1
✅ Use only one Heading 1 per page
✅ Define custom anchors for repeated headings

DON'Ts
❌ Use headings in tabs or dropdowns
❌ Go deeper than Heading 4

More details: Headings →

Standard Markdown images: [alt text] in square brackets, followed by the image path in parentheses.

![Bear emerging from hibernation](img/bear.png)

DOs
✅ Store images in a centralized directory
✅ Follow v3 best practices for screenshots
✅ Specify :screenshot: in an image directive to add a border

DON'Ts
❌ Use lots of UI screenshots that create a maintenance burden
❌ Include confidential info or PII in an image
❌ Add a drop shadow or torn edge effect

More details: Images →

Elastic Docs v3 supports standard Markdown inline formatting.

_emphasis_     italics
**strong**    bold
` monospace `     inline code (single backticks)
~~strikethrough~~     strikethrough
\* escaped     * escaped character

DOs
✅ Use _emphasis_ to introduce a term
✅ Use inline code in headings and other elements as needed

DON'Ts
❌ Overuse **strong** or _emphasis_ -- aim for readability

Standard Markdown links to doc pages, sections (anchors), or external content. Prefer absolute paths for links within the doc set.

[link text](/absolute/file.md#anchor)
[link text](https://external-site.com)
[link text](other-repo://path/file.md)
(#same-page-anchor)

DOs
✅ Use inline formatting in link text: [**bold link**](bold-page.md)
✅ Autogenerate link text from the page or section title: [](use-title.md#section)
✅ Define a custom anchor by adding [anchor-text] at the end of a heading line

DON'Ts
❌ Use unclear, inaccessible link text like "click here" or "this"
❌ Include terminal punctuation in link text

More details: Links →

Standard Markdown ordered (numbered) and unordered (bulleted) lists. Indent with four spaces to nest paragraphs and other elements under a list item. Unordered lists can start with hyphens -, asterisks *, or plus signs +.

- Unordered item 1
····Paragraph within item 1
- Unordered item 2

1. Ordered item 1
2. Ordered item 2

DOs
✅ Add code blocks, images, admonitions, and other content within a list item
✅ Nest lists, mixing ordered and unordered as needed
✅ Use parallel structure and phrasing in list items
✅ Capitalize only the first word of list items (sentence case)
✅ Use terminal punctuation consistently and only for complete sentences

DON'Ts
❌ Use lists solely for layout purposes
❌ Use lists for structured data or comparisons — use tables instead

More details: Lists →

Optional front matter element that sets a custom title for docs navigation features: appears in the left nav (table of contents), breadcrumbs, and previous/next links. Compare headings (H1 = page title).

---
  navigation_title: "Minimalist identifier"
---

# Full descriptive page title with product context

DOs
✅ Use active phrasing and shorter forms
✅ Make sure the navigation title clearly identifies the page topic
✅ Omit product names that appear in the full H1 page title

DON'Ts
❌ Duplicate the H1 page title
❌ Use a long navigation title or lots of punctuation
❌ Abbreviate with periods or ellipses

More details: Title →

Key-value pairs that define reusable variables. They help ensure consistency and enable short forms. To use a substitution (or "sub"), surround the key with curly brackets: {{variable}}

subs:
  ccs: "cross-cluster search"
  ech: "Elastic Cloud Hosted"
  kib: "Kibana"

This example uses the sub defined in docset.yml above.

{{ech}} supports most standard {{kib}} settings.

DOs
✅ Check the global docset.yml file for existing product and feature name subs
✅ Use substitutions in code blocks by setting subs=true
✅ Define new page-specific substitutions as needed

DON'Ts
❌ Override a docset.yml sub by defining a page-level sub with the same key (causes build errors)
❌ Use substitutions for common words that don't need to be standardized

More details: Substitutions →

Block element that displays content in switchable tabs to help users zero in on the right context (such as a deployment or language). Synced tab groups are supported.

::::{tab-set}

:::{tab-item} Tab 1 title
Tab 1 content
:::

:::{tab-item} Tab 2 title
Tab 2 content
:::

::::

DOs
✅ Use clear, descriptive tab labels
✅ Make sure all tabs have the same type of content and similar goals
✅ Keep tab content scannable and self-contained (don't make the user switch tabs to follow steps or compare content)
✅ Include other block elements in tabs, like admonitions

DON'Ts
❌ Nest tabs
❌ Split step-by-step procedures across tabs
❌ Use more than 6 tabs (use as few as possible)
❌ Use tabs in dropdowns

More details: Tabs →

Standard table layout for structured data. Automatically scrolls horizontally if needed. The header row is optional.

| Header | Header |
| ------ | ------ |
| Data   | Info   |
| Info	 | Data   |

DOs
✅ Use leading and trailing pipes for clarity
✅ Add spaces for readability (they're trimmed)
✅ Keep cell content scannable and parallel
✅ Use standard Markdown text alignment when necessary (:-- --: :--:)

DON'Ts
❌ Insert block elements or multiple paragraphs in a table cell
❌ Use a table solely for position or spacing purposes

More details: Tables →