Refactor Markdown directives for updated syntax compatibility (#199)

Mpdreamz · reakaleek · web-flow · commit ddd64a5a0993 · 2025-01-14T22:47:54.000+01:00
Co-authored-by: Jan Calanog &lt;jan.calanog@elastic.co&gt;
diff --git a/docs/source/docset.yml b/docs/source/docset.yml
@@ -17,6 +17,7 @@ external_hosts:
   - palletsprojects.com
   - google.com
   - checkvist.com
+  - commonmark.org
 exclude:
   - '_*.md'
 subs:
@@ -64,6 +65,7 @@ toc:
   - folder: syntax
     children:
       - file: index.md
+      - file: md-extensions.md
       - file: admonitions.md
       - file: automated_settings.md
       - file: code.md
diff --git a/docs/source/syntax/_snippets/reusable-snippet.md b/docs/source/syntax/_snippets/reusable-snippet.md
@@ -1,5 +1,5 @@
 This is a snippet included on "{{page_title}}".
 
-```{tip}
+:::{tip}
 This is a snippet
-```
+:::
diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md
@@ -39,9 +39,9 @@ This is a warning.
 :::
 ```
 
-```{warning}
+:::{warning}
 This is a warning.
-```
+:::
 
 ### Tip
 
@@ -53,9 +53,9 @@ This is a tip.
 :::
 ```
 
-```{tip}
+:::{tip}
 This is a tip.
-```
+:::
 
 ### Important
 
@@ -67,15 +67,15 @@ This is an important notice.
 :::
 ```
 
-```{important}
+:::{important}
 This is an important notice.
-```
+:::
 
 ## Collapsible admonitions
 
-```{tip}
+:::{tip}
 Also see [dropdowns](./dropdowns.md).
-```
+:::
 
 Use `:open: <bool>` to make an admonition collapsible.
 
@@ -89,13 +89,13 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 :::
 ```
 
-```{note}
+:::{note}
 :open:
 
 Longer content can be collapsed to take less space.
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-```
+:::
 
 ---
 
diff --git a/docs/source/syntax/automated_settings.md b/docs/source/syntax/automated_settings.md
@@ -32,5 +32,5 @@ groups:
 
 _Everything below this line is auto-generated._
 
-```{settings} /syntax/kibana-alerting-action-settings.yml
-```
+:::{settings} /syntax/kibana-alerting-action-settings.yml
+:::
diff --git a/docs/source/syntax/code.md b/docs/source/syntax/code.md
@@ -74,9 +74,9 @@ var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
 var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
 ```
 
-```{note}
+:::{note}
 the comments have the follow code to be hoisted as a callout.
-```
+:::
 
 ````markdown
 ```csharp
diff --git a/docs/source/syntax/conditionals.md b/docs/source/syntax/conditionals.md
@@ -2,6 +2,6 @@
 title: Conditionals
 ---
 
-```{warning}
+:::{warning}
 This feature is not currently supported in Elastic Docs V3.
-```
+:::
diff --git a/docs/source/syntax/dropdowns.md b/docs/source/syntax/dropdowns.md
@@ -27,10 +27,10 @@ Dropdown content
 :::
 ```
 
-```{dropdown} Dropdown Title
+:::{dropdown} Dropdown Title
 :open:
 Dropdown content
-```
+:::
 
 ## Asciidoc syntax
 
diff --git a/docs/source/syntax/example_blocks.md b/docs/source/syntax/example_blocks.md
@@ -2,6 +2,6 @@
 title: Example blocks
 ---
 
-```{warning}
+:::{warning}
 This feature is not currently supported in Elastic Docs V3.
-```
+:::
diff --git a/docs/source/syntax/images.md b/docs/source/syntax/images.md
@@ -12,9 +12,9 @@ Images can be referenced from the top-level `_static` dir or a local image dir.
 
 Screenshots are images displayed with a box-shadow.
 
-```{warning}
+:::{warning}
 This feature is not currently supported in Elastic Docs V3.
-```
+:::
 
 ## Block-level images
 
@@ -33,10 +33,10 @@ Or, use the `image` directive.
 :::
 ```
 
-```{image} /_static/img/observability.png
+:::{image} /_static/img/observability.png
 :alt: Elasticsearch
 :width: 250px
-```
+:::
 
 ## Inline images
 
diff --git a/docs/source/syntax/md-extensions.md b/docs/source/syntax/md-extensions.md
@@ -0,0 +1,72 @@
+---
+title: Markdown Syntax Extensions
+title_navigation: Markdown Syntax
+---
+
+## Syntax
+
+The new documentation fully supports [CommonMark](https://commonmark.org/) Markdown syntax. 
+
+On top of this widely accepted feature set we have various extensions points. 
+
+## Directives 
+
+Directives are our main extension point over markdown and follows the following syntax
+
+
+```markdown
+:::{EXTENSION} ARGUMENTS
+:OPTION: VALUE
+
+Nested content that will be parsed as markdown
+:::
+```
+
+- `EXTENSION` is the name of the directive e.g [`note`](admonitions.md#note)
+- `ARGUMENT` some directives take a main argumnt e.g [`:::{include} _snippets/include.md`](file_inclusion.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 `{ }`.
+
+### Nesting Directives
+
+You can increase the leading semicolons to include nested directives. Here the `{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
+
+For best editor compatability it is recommended to use triple backticks for content that needs to be displayed literally
+
+````markdown
+```js
+const x = 1;
+```
+````
+
+Many markdown editors support syntax highlighting for embedded code blocks.
+
+## Github Flavored Markdown
+
+We support some of GitHub flavor markdown extensions these are highlighted in green here: https://github.github.com/gfm/
+
+Supported:
+
+* GFM Tables [](tables.md#github-flavored-markdown-gfm-table)
+* Strikethrough ~~as seen here~~
+
+Not supported:
+
+* Task lists
+* Auto links (http://www.elastic.co)
+* Using a subset of html 
+
diff --git a/docs/source/syntax/passthrough.md b/docs/source/syntax/passthrough.md
@@ -2,6 +2,6 @@
 title: Passthrough blocks
 ---
 
-```{warning}
+:::{warning}
 This feature is not currently supported in Elastic Docs V3.
-```
+:::
diff --git a/docs/source/syntax/sidebars.md b/docs/source/syntax/sidebars.md
@@ -2,6 +2,6 @@
 title: Sidebars
 ---
 
-```{warning}
+:::{warning}
 This feature is not currently supported in Elastic Docs V3.
-```
+:::
diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs
@@ -34,7 +34,7 @@ public DirectiveBlockParser()
 
 	private readonly string[] _codeBlocks = ["code", "code-block", "sourcecode"];
 
-	private readonly FrozenDictionary<string, int> _unsupportedBlocks = new Dictionary<string, int>
+	private static readonly FrozenDictionary<string, int> UnsupportedBlocks = new Dictionary<string, int>
 	{
 		{ "bibliography", 5 },
 		{ "blockquote", 6 },
@@ -63,17 +63,19 @@ public DirectiveBlockParser()
 		{ "seealso", 3 }
 	}.ToFrozenDictionary();
 
+	private static readonly FrozenDictionary<string, int>.AlternateLookup<ReadOnlySpan<char>> UnsupportedLookup =
+		UnsupportedBlocks.GetAlternateLookup<ReadOnlySpan<char>>();
+
 	protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 	{
 		var info = processor.Line.AsSpan();
 
 		if (processor.Context is not ParserContext context)
 			throw new Exception("Expected parser context to be of type ParserContext");
 
-		// TODO alternate lookup .NET 9
-		var directive = info.ToString().Trim(['{', '}', '`']);
-		if (_unsupportedBlocks.TryGetValue(directive, out var issueId))
-			return new UnsupportedDirectiveBlock(this, directive, issueId, context);
+		var directive = info.Trim(['{', '}', '`', ':']);
+		if (UnsupportedLookup.TryGetValue(directive, out var issueId))
+			return new UnsupportedDirectiveBlock(this, directive.ToString(), issueId, context);
 
 		if (info.IndexOf("{tab-set}") > 0)
 			return new TabSetBlock(this, context);
diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs
@@ -9,9 +9,9 @@ namespace Elastic.Markdown.Tests.Directives;
 
 public abstract class AdmonitionTests(ITestOutputHelper output, string directive) : DirectiveTest<AdmonitionBlock>(output,
 $$"""
-```{{{directive}}}
+:::{{{directive}}}
 This is an attention block
-```
+:::
 A regular paragraph.
 """
 )
@@ -65,10 +65,10 @@ A regular paragraph.
 
 public class DropdownTitleTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
 """
-```{dropdown} This is my custom dropdown
+:::{dropdown} This is my custom dropdown
 :open:
 This is an attention block
-```
+:::
 A regular paragraph.
 """
 )
diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs
@@ -11,11 +11,11 @@ namespace Elastic.Markdown.Tests.Directives;
 public abstract class AdmonitionUnsupportedTests(ITestOutputHelper output, string directive)
 	: DirectiveTest<UnsupportedDirectiveBlock>(output,
 $$"""
-  ```{{{directive}}}
-  This is an attention block
-  ```
-  A regular paragraph.
-  """
+:::{{{directive}}}
+This is an attention block
+:::
+A regular paragraph.
+"""
 	)
 {
 	[Fact]
diff --git a/tests/Elastic.Markdown.Tests/Directives/AppliesBlockTests.cs b/tests/Elastic.Markdown.Tests/Directives/AppliesBlockTests.cs
@@ -12,9 +12,9 @@ namespace Elastic.Markdown.Tests.Directives;
 public class AppliesBlockTests(ITestOutputHelper output) : DirectiveTest<AppliesBlock>(output,
 """
 # heading
-```{applies}
+:::{applies}
 :eck: unavailable
-```
+:::
 """
 )
 {
diff --git a/tests/Elastic.Markdown.Tests/Directives/ImageTests.cs b/tests/Elastic.Markdown.Tests/Directives/ImageTests.cs
@@ -12,10 +12,10 @@ namespace Elastic.Markdown.Tests.Directives;
 
 public class ImageBlockTests(ITestOutputHelper output) : DirectiveTest<ImageBlock>(output,
 """
-```{image} img/observability.png
+:::{image} img/observability.png
 :alt: Elasticsearch
 :width: 250px
-```
+:::
 """
 )
 {
@@ -43,13 +43,13 @@ public void ImageIsFoundSoNoErrorIsEmitted()
 
 public class FigureTests(ITestOutputHelper output) : DirectiveTest<ImageBlock>(output,
 """
-```{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true
+:::{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true
 :label: myFigure
 :alt: Sunset at the beach
 :align: center
 
 Relaxing at the beach 🏝 🌊 😎
-```
+:::
 """
 )
 {
diff --git a/tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs b/tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs
@@ -10,7 +10,7 @@ namespace Elastic.Markdown.Tests.Directives;
 
 public class MermaidBlockTests(ITestOutputHelper output) : DirectiveTest<MermaidBlock>(output,
 """
-```{mermaid} /_static/img/observability.png
+:::{mermaid} /_static/img/observability.png
 flowchart LR
   A[Jupyter Notebook] --> C
   B[MyST Markdown] --> C
@@ -21,7 +21,7 @@ B[MyST Markdown] --> C
   D --> H[React]
   D --> I[HTML]
   D <--> J[JATS]
-```
+:::
 """
 )
 {
diff --git a/tests/Elastic.Markdown.Tests/Directives/TabTests.cs b/tests/Elastic.Markdown.Tests/Directives/TabTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Directives/VersionTests.cs b/tests/Elastic.Markdown.Tests/Directives/VersionTests.cs
diff --git a/tests/Elastic.Markdown.Tests/FileInclusion/IncludeTests.cs b/tests/Elastic.Markdown.Tests/FileInclusion/IncludeTests.cs
diff --git a/tests/Elastic.Markdown.Tests/FileInclusion/LiteralIncludeTests.cs b/tests/Elastic.Markdown.Tests/FileInclusion/LiteralIncludeTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs b/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs
diff --git a/tests/Elastic.Markdown.Tests/SettingsInclusion/IncludeTests.cs b/tests/Elastic.Markdown.Tests/SettingsInclusion/IncludeTests.cs
