[docs] Simplify syntax landing page, factor our directives information into standalone page (#2054)

Author: leemthompo

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

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}

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

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