diff --git a/docs/_docset.yml b/docs/_docset.yml index bad2fe7e4..ed1e8aa7d 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -93,6 +93,7 @@ toc: - file: conditionals.md - file: csv-include.md - hidden: diagrams.md + - file: directives.md - file: dropdowns.md - file: definition-lists.md - file: example_blocks.md diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 770d91aa3..365c22f47 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -52,7 +52,7 @@ All documentation pages must include an `applies_to` tag in the YAML frontmatter A header can be followed by an `{applies_to}` directive which contextualizes the applicability of the section further. -Section-level `{applies_to}` directives require triple backticks because their content is literal. Refer to [](index.md#literal-directives) for more information. +Section-level `{applies_to}` directives require triple backticks because their content is literal. Refer to [](directives.md#exception-literal-blocks) for more information. ````markdown ```{applies_to} diff --git a/docs/syntax/directives.md b/docs/syntax/directives.md new file mode 100644 index 000000000..2984deb28 --- /dev/null +++ b/docs/syntax/directives.md @@ -0,0 +1,79 @@ +# Directives + +Directives extend Markdown with additional features: + +```markdown +:::{note} +This is a callout box that stands out from regular text. +::: +``` + +How directive syntax works: +- `:::` opens and closes the directive block +- `{note}` is the directive type (always in curly braces) +- Content inside is regular Markdown + +## Adding options + +```markdown +:::{image} screenshot.png +:alt: Dashboard overview <1> +:width: 600px +::: +``` + +1. Options start with `:` and appear after the opening line. + +## Adding arguments + +```markdown +:::{include} shared-content.md +::: +``` + +The argument comes right after the directive name. + +## Nesting directives + +To nest directives, add more colons to the outer directive: + +```markdown +::::{note} +Outer content + +:::{hint} +Inner content +::: + +More outer content +:::: +``` + +Use four colons (`::::`) for the outer directive and three (`:::`) for the inner one. Need to nest deeper? Keep adding colons. + +## Exception: Literal blocks + +Code blocks and [`applies_to` blocks](applies.md) use backticks instead of colons to prevent content from being processed as Markdown: + +````markdown +```js +const x = 1; +``` +```` + +## Available directives + +The following directives are available: + +- [Admonitions](admonitions.md) - Callouts and warnings +- [Code blocks](code.md) - Syntax-highlighted code +- [CSV include](csv-include.md) - Render CSV files as tables +- [Diagrams](diagrams.md) - Visual diagrams and charts +- [Dropdowns](dropdowns.md) - Collapsible content +- [Images](images.md) - Enhanced image handling +- [Include](file_inclusion.md) - Include content from other files +- [Settings](automated_settings.md) - Configuration blocks +- [Stepper](stepper.md) - Step-by-step content +- [Tabs](tabs.md) - Tabbed content organization +- [Tables](tables.md) - Data tables +- [Version blocks](version-variables.md) - API version information \ No newline at end of file diff --git a/docs/syntax/index.md b/docs/syntax/index.md index 188d3e8d4..ce7c31859 100644 --- a/docs/syntax/index.md +++ b/docs/syntax/index.md @@ -1,97 +1,29 @@ # Syntax guide -Elastic Docs V3 uses [Markdown](https://commonmark.org) as its main content authoring format. +Learn about the custom Markdown syntax used in Elastic documentation. -:::{admonition} New to Elastic Docs V3? -* Learn [Markdown](https://commonmark.org/help/) in 10 minutes -* Review the V3 [](quick-ref.md) -::: +## Quick reference -V3 fully supports [CommonMark](https://commonmark.org/), 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: +Refer to the [quick reference](quick-ref.md) for a condensed syntax cheat sheet. -* [Directives](#directives) -* [GitHub-flavored markdown](#github-flavored-markdown) +## How it works -## Available directives +Elastic Docs V3 uses a custom implementation of [MyST](https://mystmd.org/) (Markedly Structured Text), which extends standard Markdown with directive syntax. -The following directives are available in Elastic Docs V3: +If you know [Markdown](https://commonmark.org), you already know most of what you need. If not, the CommonMark project offers a [10-minute tutorial](https://commonmark.org/help/). -* [Admonitions](admonitions.md) - Callouts and warnings -* [Code blocks](code.md) - Syntax-highlighted code -* [CSV include](csv-include.md) - Render CSV files as tables -* [Diagrams](diagrams.md) - Visual diagrams and charts -* [Dropdowns](dropdowns.md) - Collapsible content -* [Images](images.md) - Enhanced image handling -* [Include](file_inclusion.md) - Include content from other files -* [Settings](automated_settings.md) - Configuration blocks -* [Stepper](stepper.md) - Step-by-step content -* [Tabs](tabs.md) - Tabbed content organization -* [Tables](tables.md) - Data tables -* [Version blocks](version-variables.md) - API version information +When you need more than basic Markdown, you can use [directives](directives.md) to add features like callouts, tabs, and diagrams. -## Directives +## GitHub Flavored Markdown support -Directives extend CommonMark functionality. Directives have the following syntax: +V3 supports some GitHub Flavored Markdown extensions: -```markdown -:::{EXTENSION} ARGUMENTS -:OPTION: VALUE +**Supported:** +- Tables (basic pipe syntax) +- Strikethrough with `~~text~~` (renders as ~~text~~) -Nested content that will be parsed as markdown -::: -``` - -- `EXTENSION` is the name of the directive. Names are always wrapped in brackets `{ }`. For example: [`{note}`](admonitions.md#note). -- `ARGUMENT` an optional main argument. For example: [`:::{include} _snippets/include.md :::`](file_inclusion.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. - - - -### Nesting Directives - -Increase the number of leading semicolons to include nested directives. - -In the following example, a `{note}` wraps a `{hint}`: - -```markdown -::::{note} My note -:::{hint} My hint -Content displayed in the hint admonition -::: -Content displayed in the note admonition -:::: -``` - -## Literal directives - -All directive are indicated with semicolons except literal blocks. For these you need to use triple backticks. - -* [Code blocks](code.md) -* [{applies-to} blocks](applies.md) - -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: - -````markdown -```js -const x = 1; -``` -```` - -## GitHub Flavored Markdown - -We support _some_ [GitHub Flavored Markdown (GFM) extensions](https://github.github.com/gfm/). - -### Supported - -* [](tables.md#basic-table) -* Strikethrough: ~~as seen here~~ - -### Not supported - -* Task lists -* Auto links (http://www.elastic.co) -* Using a subset of HTML +**Not supported:** +- Task lists +- Automatic URL linking: https://www.elastic.co + - Links must use standard Markdown syntax: [Elastic](https://www.elastic.co) +- Using a subset of HTML \ No newline at end of file