Update usages of :::none, make sure code is written escaping html and ensure callouts are not parsed from example markdown

Author: Mpdreamz

docs/source/docset.yml

@@ -25,7 +25,6 @@ toc:
       - file: admonitions.md
       - file: automated_settings.md
       - file: code.md
-      - file: code-callouts.md
       - file: conditionals.md
       - file: dropdowns.md
       - file: example_blocks.md

docs/source/syntax/admonitions.md

@@ -29,12 +29,12 @@ Admonitions can span multiple lines and support inline formatting.
 
 A relevant piece of information with no serious repercussions if ignored.
 
-:::none
-\`\`\`\{note}
+```markdown
+:::{note}
 This is a note.
 It can span multiple lines and supports inline formatting.
-\`\`\`
 :::
+```
 
 :::{note}
 This is a note.
@@ -44,11 +44,11 @@ This is a note.
 
 You could permanently lose data or leak sensitive information.
 
-:::none
-\`\`\`\{caution}
+```markdown
+:::{caution}
 This is a caution.
-\`\`\`
 :::
+```
 
 ```{caution}
 This is a caution.
@@ -58,11 +58,11 @@ This is a caution.
 
 Advice to help users make better choices when using a feature.
 
-:::none
-\`\`\`\{tip}
+```markdown
+:::{tip}
 This is a tip.
-\`\`\`
 :::
+```
 
 ```{tip}
 This is a tip.
@@ -72,11 +72,11 @@ This is a tip.
 
 Ignoring this information could impact performance or the stability of your system.
 
-:::none
-\`\`\`\{attention}
+```markdown
+:::{attention}
 This is an attention.
-\`\`\`
 :::
+```
 
 ```{attention}
 This is an attention.
@@ -96,37 +96,38 @@ This is an attention.
 
 
 **Inline Admonition:**
-:::none
+```none
 NOTE: This is a note.
 It can be multiple lines, but not multiple paragraphs.
-:::
+```
 
 **Block Admonition:**
-:::none
+
+```none
 [WARNING]
 =======
 This is a warning.
 
 It can contain multiple paragraphs.
 =======
 :::
-````
+```
 
 `````
 
 ## Collapsible admonitions
 
 You can use `:open: <bool>` to make an admonition collapsible.
 
-:::none
-\`\`\`\{note}
+```none
+:::{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.
-\`\`\`
 :::
+```
 
 ```{note}
 :open:

docs/source/syntax/automated_settings.md

@@ -6,10 +6,10 @@ Elastic Docs V3 supports the ability to build a markdown settings reference from
 
 ### Syntax
 
-:::none
-\`\`\`\{settings} /syntax/kibana-alerting-action-settings.yml
-\`\`\`
+```none
+:::{settings} /syntax/kibana-alerting-action-settings.yml
 :::
+```
 
 ### Result
 

docs/source/syntax/code-callouts.md

@@ -6,13 +6,13 @@ Code blocks can be used to display multiple lines of code. They preserve formatt
 
 ### Syntax
 
-:::none
-\`\`\`yaml
+````markdown
+```yaml
 project:
   title: MyST Markdown
   github: https://github.com/jupyter-book/mystmd
-\`\`\`
-:::
+```
+````
 
 ```yaml
 project:
@@ -22,15 +22,74 @@ project:
 
 ### Asciidoc syntax
 
-:::none
+```none
 [source,sh]
 --------------------------------------------------
 GET _tasks
 GET _tasks?nodes=nodeId1,nodeId2
 GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:*
 --------------------------------------------------
-:::
+```
 
 ### Code blocks with callouts
 
-_coming soon!_
+A code block can include `<\d+>` at the end to indicate code callouts. 
+A code block with this style of callouts **needs** to be followed by an ordered list with an equal amount of items as called out. 
+Otherwise, the docs-builder will throw an error.
+
+This syntax mimics what was implemented for our asciidoc system
+
+````markdown
+```yaml
+project:
+  title: MyST Markdown 
+  github: https://github.com/jupyter-book/mystmd
+  license:
+    code: MIT
+    content: CC-BY-4.0 <1>
+  subject: MyST Markdown 
+```
+
+1. The license
+````
+
+
+### Magic Callout 
+
+You can include the callouts also directly as code using either `//` or `#` comments.
+
+These will then be listed and numbered automatically
+
+````markdown
+```csharp
+var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+```
+````
+
+Will output:
+
+```csharp
+var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+```
+
+```{note} 
+the comments have the follow code to be hoisted as a callout.
+```
+
+````markdown
+```csharp
+// THIS IS NOT A CALLOUT
+var apiKey = new ApiKey("<API_KEY>"); // However this is
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+```
+````
+
+will output:
+
+```csharp
+// THIS IS NOT A CALLOUT
+var apiKey = new ApiKey("<API_KEY>"); // However this is
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+```

docs/source/syntax/code.md

@@ -8,19 +8,19 @@ Dropdowns allow you to hide and reveal content on user interaction.
 
 By default, dropdowns are collapsed. This hides content until a user clicks the title of the collapsible block.
 
-:::none
-\`\`\`\{dropdown} Dropdown Title
+```markdown
+:::{dropdown} Dropdown Title
 Dropdown content
-\`\`\`
 :::
+```
 
-```{dropdown} Dropdown Title
+:::{dropdown} Dropdown Title
 Dropdown content
-```
+:::
 
 ### Asciidoc syntax
 
-:::none
+```asciidoc
 .The `elasticsearch-setup-passwords` tool is deprecated.
 [%collapsible]
 ====
@@ -38,18 +38,18 @@ for the first time. If you run `elasticsearch-setup-passwords` after
 starting {es}, it will fail because the `elastic`
 user password is already configured.
 ====
-:::
+```
 
 ### Open by default
 
 You can also specify that the content should be visible by default, but can also be collapsed by the user. Do this by specifying the `open` option.
 
-:::none
-\`\`\`\{dropdown} Dropdown Title
+```markdown
+:::{dropdown} Dropdown Title
 :open:
 Dropdown content
-\`\`\`
 :::
+```
 
 ```{dropdown} Dropdown Title
 :open:

docs/source/syntax/dropdowns.md

@@ -11,16 +11,16 @@ If there are portions of content that are relevant to multiple pages, you can in
 
 ### Syntax
 
-:::none
-\`\`\`\{include} _snippets/my_snippet.md
-\`\`\`
+```markdown
+:::{include} _snippets/my_snippet.md
 :::
-
-```{include} _snippets/my_snippet.md
 ```
 
+:::{include} _snippets/my_snippet.md
+:::
+
 ### Asciidoc syntax
 
-:::none
+```asciidoc
 include::shared-monitor-config.asciidoc[]
-:::
+```

docs/source/syntax/file_inclusion.md

@@ -16,20 +16,20 @@ Screenshots get a box-shadow.
 
 ## Block-level images
 
-:::none
-\!\[APM](/_static/img/apm.png)
-:::
+```markdown
+![APM](/_static/img/apm.png)
+```
 
 ![APM](/_static/img/apm.png)
 
 Or, use the `image` directive.
 
-:::none
-\`\`\`\{image} /_static/img/observability.png
+```markdown
+:::{image} /_static/img/observability.png
 :alt: Elasticsearch
 :width: 250px
-\`\`\`
 :::
+```
 
 ```{image} /_static/img/observability.png
 :alt: Elasticsearch
@@ -38,19 +38,19 @@ Or, use the `image` directive.
 
 ## Inline image
 
-:::none
-Here is the same image used inline \!\[Elasticsearch](/_static/img/observability.png)\{width=30px}
-:::
+```markdown
+Here is the same image used inline ![Elasticsearch](/_static/img/observability.png)
+```
 
-Here is the same image used inline ![Elasticsearch](/_static/img/observability.png){width=30px}.
+Here is the same image used inline ![Elasticsearch](/_static/img/observability.png)
 
 ## Asciidoc syntax
 
-:::none
+```asciidoc
 [role="screenshot"]
 image::images/metrics-alert-filters-and-group.png[Metric threshold filter and group fields]
-:::
+```
 
-:::none
+```asciidoc
 image::images/synthetics-get-started-projects.png[]
-:::
+```