From 366af9c1fb7e9254894172224ff5a966a0cf83d7 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 14:10:26 -0500 Subject: [PATCH 01/12] Write .md generation spec --- content/en/md_conversion_test_files/README.md | 24 ++++++ .../common_components/alert.md | 25 ++++++ .../common_components/callouts.md | 24 ++++++ .../common_components/code_blocks.md | 60 ++++++++++++++ .../common_components/collapsible_sections.md | 30 +++++++ .../common_components/further_reading.md | 20 +++++ .../common_components/images_and_videos.md | 17 ++++ .../common_components/plain_markdown.md | 80 +++++++++++++++++++ .../programming_lang_wrapper.md | 39 +++++++++ .../common_components/region_shortcodes.md | 36 +++++++++ .../common_components/tables.md | 72 +++++++++++++++++ .../common_components/tabs.md | 32 ++++++++ .../common_components/tile_partial.md | 43 ++++++++++ .../common_components/tooltip.md | 17 ++++ .../do_not_process/private_page.md | 8 ++ .../uncommon_components/agent_config.md | 15 ++++ .../dashboard_widgets_api.md | 12 +++ .../expression_language_evaluator.md | 15 ++++ .../uncommon_components/header_list.md | 18 +++++ .../uncommon_components/icon.md | 11 +++ .../uncommon_components/integration_count.md | 11 +++ .../uncommon_components/kbd.md | 11 +++ .../uncommon_components/math.md | 12 +++ .../uncommon_components/permissions.md | 11 +++ 24 files changed, 643 insertions(+) create mode 100644 content/en/md_conversion_test_files/README.md create mode 100644 content/en/md_conversion_test_files/common_components/alert.md create mode 100644 content/en/md_conversion_test_files/common_components/callouts.md create mode 100644 content/en/md_conversion_test_files/common_components/code_blocks.md create mode 100644 content/en/md_conversion_test_files/common_components/collapsible_sections.md create mode 100644 content/en/md_conversion_test_files/common_components/further_reading.md create mode 100644 content/en/md_conversion_test_files/common_components/images_and_videos.md create mode 100644 content/en/md_conversion_test_files/common_components/plain_markdown.md create mode 100644 content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md create mode 100644 content/en/md_conversion_test_files/common_components/region_shortcodes.md create mode 100644 content/en/md_conversion_test_files/common_components/tables.md create mode 100644 content/en/md_conversion_test_files/common_components/tabs.md create mode 100644 content/en/md_conversion_test_files/common_components/tile_partial.md create mode 100644 content/en/md_conversion_test_files/common_components/tooltip.md create mode 100644 content/en/md_conversion_test_files/do_not_process/private_page.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/agent_config.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/dashboard_widgets_api.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/header_list.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/icon.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/integration_count.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/kbd.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/math.md create mode 100644 content/en/md_conversion_test_files/uncommon_components/permissions.md diff --git a/content/en/md_conversion_test_files/README.md b/content/en/md_conversion_test_files/README.md new file mode 100644 index 0000000000000..b13b5a6a77db7 --- /dev/null +++ b/content/en/md_conversion_test_files/README.md @@ -0,0 +1,24 @@ +--- +title: Plaintext Markdown Spec +--- + +## What is this? + +This folder contains a listing of the components used on the docs site, and a description of their desired output format in the plaintext files generated for AI agents. + +The HTML compiled from these files will be used as the test input HTML for the Markdown generator job. + +## Where can I learn more? + +1. Read [Datadog Docs for AI Agents](https://docs.google.com/document/d/1t48N0uDJElMP_228n2bIYi_cUIj_xMOKjdHuh1Z4rMg), which attempts to summarize the problem space and why this is important. +2. Ask Jen Gilbert. + +## Disclaimer + +Everything described here is *probably* possible based on the technical context and existing libraries we have so far, but it's not *guaranteed* to be possible until the docs are migrated to Markdoc. + +If you'd like to follow along with changes in the spec, Jen will keep this PR up to date, with clear commit messages about what changed. + +## Feedback is welcome! + +Jen took her best shot at these, but she's not attached to any of it. Comment away! \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/alert.md b/content/en/md_conversion_test_files/common_components/alert.md new file mode 100644 index 0000000000000..ac37331eee4c7 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/alert.md @@ -0,0 +1,25 @@ +--- +title: Alert +--- + +## Expected .md output + +Each alert is bordered with `[BEGIN ALERT]` and `[END ALERT]`. For example, `[BEGIN INFO ALERT]`. + +### Info + +
This is an info alert.
+ +This is a random sentence. + +### Warning + +
This is a warning alert containing an HTML link.
+ +This is a random sentence. + +### Danger + +
This is a danger alert.
+ +This is a random sentence. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/callouts.md b/content/en/md_conversion_test_files/common_components/callouts.md new file mode 100644 index 0000000000000..08f450c05234c --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/callouts.md @@ -0,0 +1,24 @@ +--- +title: Callouts +--- + +## Expected .md output + +- Each callout is marked by `[BEGIN CALLOUT]` and `[END CALLOUT]`. +- Any attributes, such as the title or the URL, are included in the box contents: + - The title is a heading at the top of the box. + - The URL is included with verbiage at the bottom like "Visit this URL: ". + +## Example inputs + +### Callout (preview / beta) + +{{< callout url="https://www.datadoghq.com/">}} + Datadog Apps are in Preview. Request access by using this form. Once approved, you can start getting creative and develop your App for you, your organization, or for publishing to the entire Datadog community alongside our other great Datadog Apps! +{{< /callout >}} + +### Learning center callout + +{{< learning-center-callout header="Try Foundations in the Learning Center" btn_title="Enroll Now" btn_url="https://learn.datadoghq.com/courses/datadog-foundation">}} + The Datadog Learning Center is full of hands-on courses to help you learn about this topic. Enroll today to learn more about Datadog Foundations. +{{< /learning-center-callout >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/code_blocks.md b/content/en/md_conversion_test_files/common_components/code_blocks.md new file mode 100644 index 0000000000000..9adcebfd8f475 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/code_blocks.md @@ -0,0 +1,60 @@ +--- +title: Code Blocks +--- + +## Scope + +This covers the `code-block` and `highlight` shortcodes. Plain fences are already covered in the "plain markdown" examples. + +## Expected .md output + +Each code block is wrapped in a fence, with the language included when available: + +```lang +Code contents here. +``` + +### Filenames + +When a filename is present, it appears above the code block, like this: + +In the `block.java` file: + +```lang +Code contents here. +``` + +### Highlighted lines + +When a highlight is present, it appears above the code block, like this: + +See lines 2-3 below: + +```lang +Code contents here. +``` + +## Example inputs + +### Code block + +{{< code-block lang="java" filename="block.java" disable_copy="true" collapsible="true" >}} +import com.datadoge.docs.SweetCodeBlock; +import com.datadoge.docs.TryItOut; +public class CodeBlocksForLife { + ... + } +{{< /code-block >}} + +### Highlighted code block + +{{< highlight yaml "hl_lines=6-8" >}} + apiVersion: apps/v1 + kind: Deployment + metadata: + name: springfront + labels: + tags.datadoghq.com/env: "dev" + tags.datadoghq.com/service: "springfront" + tags.datadoghq.com/version: "12" + {{< /highlight >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/collapsible_sections.md b/content/en/md_conversion_test_files/common_components/collapsible_sections.md new file mode 100644 index 0000000000000..d887340ea939b --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/collapsible_sections.md @@ -0,0 +1,30 @@ +--- +title: Collapsible Sections +--- + +## Expected .md output + +Each section begins and ends with a box marker: `[BEGIN BOX]` and `[END BOX]`. + +## Example inputs + +### Details + +This content is outside the `details` tag. + +
+ Details + This content would be hidden inside the details panel. +
+ +This content is outside the `details` tag. + +### Collapse content + +This content is outside the `content-collapse` block. + +{{% collapse-content title="Datadog Operator" level="h4" expanded=false id="id-for-anchoring" %}} +This content is inside the `content-collapse` block. +{{% /collapse-content %}} + +This content is outside the `content-collapse` block. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/further_reading.md b/content/en/md_conversion_test_files/common_components/further_reading.md new file mode 100644 index 0000000000000..53e829783ff79 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/further_reading.md @@ -0,0 +1,20 @@ +--- +title: Further Reading +further_reading: + - link: "logs/processing/pipelines" + tag: "Documentation" + text: "Log processing pipelines" + - link: "some/blog/post" + tag: "Blog" + text: "Some blog post" +--- + +## Expected .md output + +A list of links, introduced by the text "Further reading:". + +## Example input + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/images_and_videos.md b/content/en/md_conversion_test_files/common_components/images_and_videos.md new file mode 100644 index 0000000000000..d71d506766ddf --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/images_and_videos.md @@ -0,0 +1,17 @@ +--- +title: Images and Videos +--- + +## Expected .md output + +A placeholder including relevant information about the asset, such as `[IMAGE src="some/src/path" alt="some alt text"]`. + +## Example inputs + +## Image + +{{< img src="path/to/your/image-name-here.png" alt="Your image description" caption="Your image description" style="width:100%;" >}} + +## Video + +{{< img src="path/to/your/video-name-here.mp4" alt="Your image description" video="true" width="100%" >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/plain_markdown.md b/content/en/md_conversion_test_files/common_components/plain_markdown.md new file mode 100644 index 0000000000000..68a20e3138309 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/plain_markdown.md @@ -0,0 +1,80 @@ +--- +title: Plain Markdown Elements +--- + +## Expected .md output + +- Most of this should remains unchanged, or uses a format that does not meaningfully differ from its original form. (Some spacing changes can be difficult to avoid.) +- In some cases, content may be slightly optimized for agents (for example, links will become inline). + +## Headings + +### Heading level 3 + +Some text. + +#### Heading level 4 {#heading-level-4} + +Some text, with a custom heading ID. + +##### Heading level 5 + +Some text. + +###### Heading level 6 + +Some text. + +## Inline text formatting + +You can *italicize* text, or **bold** it. + +Text can also be formatted as a [plain link][1], **[bold link][1]**, or *[italic link][1]*. + +## Lists + +### Ordered + +Here's an ordered list of steps: + +1. Figure out how to migrate to [Astro][2]. +2. Make some *incredible docs*. +3. **Profit.** + +### Unordered + +Here's an unordered version of the same list, which doesn't make as much sense, but that's okay. + +- Figure out how to migrate to [Astro][2]. +- Make some *incredible docs*. +- **Profit.** + +## Code + +### Inline code + +Here's some `inline code`. + +### Code fence + +```javascript +console.log("Hello, world!"); +``` + +## Description list + +Service +: Services are the building blocks of modern microservice architectures - broadly a service groups together endpoints, queries, or jobs for the purposes of building your application. + +Resource +: Resources represent a particular domain of a customer application - they are typically an instrumented web endpoint, database query, or background job. + +`clusterChecksRunner.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution` +: Required. A list of node selector terms. The terms are ORed. + +`site` +: Set the site of the Datadog intake for Agent data: {{< region-param key="dd_site" code="true" >}}. Defaults to `datadoghq.com`. + + +[1]: https://www.google.com +[2]: https://astro.build/ diff --git a/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md b/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md new file mode 100644 index 0000000000000..1388faec45b4f --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md @@ -0,0 +1,39 @@ +--- +title: Programming lang wrapper +--- + +## Expected .md output + +These are treated as tabs: + +- Each section starts with `[BEGIN TAB]` and end with `[END TAB]`. +- Each section includes its label at the top (for example, "Python"), formatted as a heading. + +## Example input + +{{< programming-lang-wrapper langs="python,ruby,PHP" >}} + +{{< programming-lang lang="python" >}} +Info about how to do this with Python. + ```python +from datadog import initialize, statsd +``` +{{< /programming-lang >}} + +{{< programming-lang lang="ruby" >}} +Info about how to do this with Ruby. + ```ruby +require 'datadog/statsd' +``` +{{< /programming-lang >}} + +{{< programming-lang lang="PHP" >}} +Info about how to do this with PHP. + ```php +}} + +{{< /programming-lang-wrapper >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/region_shortcodes.md b/content/en/md_conversion_test_files/common_components/region_shortcodes.md new file mode 100644 index 0000000000000..9f5af356ea76e --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/region_shortcodes.md @@ -0,0 +1,36 @@ +--- +title: Region Shortcodes +--- + +## Site region shortcode + +### Expected .md output + +The contents are enclosed in `[BEGIN CONTENT FOR REGIONS "ap1", "gov"]` and `[END CONTENT FOR REGIONS "ap1", "gov"]`. + +### Example input + +{{< site-region region="us,ap1" >}} +This paragraph only appears if the user has selected US or AP1 from the Site Selector dropdown. +{{< /site-region >}} + +## Region parameter shortcode + +### Expected .md output + +A placeholder: + +- `` in code. +- `[USER'S DATADOG SITE]` in copy. + +### Example inputs + +#### In code + +```shell +export DD_SITE={{< region-param key=dd_site code="true" >}} +``` + +#### In copy + +Your Datadog site is {{< region-param key=dd_site >}}. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/tables.md b/content/en/md_conversion_test_files/common_components/tables.md new file mode 100644 index 0000000000000..5993cf5bc30df --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/tables.md @@ -0,0 +1,72 @@ +--- +title: Tables +--- + +## Plain Markdown tables + +### Expected .md output + +A key-value list for each table row: + +- Name: Jen + Country: USA + Has dog?: Yes + +- Name: Kari + Country: Canada + Has dog?: No + +### Example input + +| Column 1 | Column 2 | Column 3 | Supported? | +| ------------ | ------------ | ------------ | ---------- | +| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 | {{< X >}} | +| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 | | +| Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3 | {{< X >}} | +| Row 4, Col 1 | Row 4, Col 2 | Row 4, Col 3 | | + +## HTML tables + +### Expected .md output + +Both of these should be included: + +- Whatever the generator can safely derive from the table, in "key-value list" form, with a disclaimer that the data may be incomplete. +- The raw HTML contents, for further reference. + +### Example input + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IconDescription
{{Access point icon}}Access Point
{{Firewall icon}}Firewall
{{Router icon}}Router
{{Server icon}}Server
{{Switch icon}}Switch
{{Device icon}}Device
\ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/tabs.md b/content/en/md_conversion_test_files/common_components/tabs.md new file mode 100644 index 0000000000000..7125df36bac51 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/tabs.md @@ -0,0 +1,32 @@ +--- +title: Tabs +--- + +## Expected .md output + +- Each tab starts with `[BEGIN TAB]` and end with `[END TAB]`. +- Each tab includes its label at the top (for example, "Python"), formatted as a heading. + +## Example input + +A random sentence goes here. + +{{< tabs >}} +{{% tab "Python" %}} +This tab is for Python. It has a code fence in it: + +```python +print('Hello world') +``` +{{% /tab %}} + +{{% tab "JavaScript" %}} +This tab is for JavaScript. It has a code fence in it: + +```javascript +console.log('Hello world'); +``` +{{% /tab %}} +{{< /tabs >}} + +A random sentence goes here. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/common_components/tile_partial.md b/content/en/md_conversion_test_files/common_components/tile_partial.md new file mode 100644 index 0000000000000..d39c3bfe63f59 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/tile_partial.md @@ -0,0 +1,43 @@ +--- +title: Tile partial +--- + +## Expected .md output + +A list of links that uses the image alt text as the link text. + +## Input example + +Here's a sentence before the tile partial. + +{{ $dot := . }} +
+
+
+
+ +
+ {{ partial "img.html" (dict "root" . "src" "integrations_logos/python.png" "class" "img-fluid" "alt" "Python" "width" "400") }} +
+ +
+
+ +
+ {{ partial "img.html" (dict "root" . "src" "integrations_logos/nodejs.png" "class" "img-fluid" "alt" "Node.js" "width" "400") }} +
+ +
+
+ +
+ {{ partial "img.html" (dict "root" . "src" "integrations_logos/ruby.png" "class" "img-fluid" "alt" "Ruby" "width" "400") }} +
+ +
+
+
+
+
+ +Here's a sentence after the tile partial. diff --git a/content/en/md_conversion_test_files/common_components/tooltip.md b/content/en/md_conversion_test_files/common_components/tooltip.md new file mode 100644 index 0000000000000..f3d77c02ea188 --- /dev/null +++ b/content/en/md_conversion_test_files/common_components/tooltip.md @@ -0,0 +1,17 @@ +--- +title: Tooltip +--- + +## Expected .md output + +The hidden contents of the tooltip are added as parenthetical text next to the display text of the tooltip, like this: Jen loves boba (a popular drink made of tea, milk, and tapioca pearls). + +## Example inputs + +### Custom tooltip + +Here's an example of a {{< tooltip text="tooltip" tooltip="This is additional information that appears in the tooltip" >}} in action. + +### Glossary tooltip + +Define the retention query by adding any span tag. Choose to retain all spans with the defined tags, only service entry spans (selected by default), or only a {{< tooltip glossary="trace root span" >}}. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/do_not_process/private_page.md b/content/en/md_conversion_test_files/do_not_process/private_page.md new file mode 100644 index 0000000000000..18470ad1aba65 --- /dev/null +++ b/content/en/md_conversion_test_files/do_not_process/private_page.md @@ -0,0 +1,8 @@ +--- +title: A Private Page +private: true +--- + +## Overview + +This is a private page. The Markdown generator should not process it at all, and we should verify that it does not exist in the generated output. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/agent_config.md b/content/en/md_conversion_test_files/uncommon_components/agent_config.md new file mode 100644 index 0000000000000..ecbe4649b53d5 --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/agent_config.md @@ -0,0 +1,15 @@ +--- +title: Agent config +--- + +## Expected .md output + +A yaml code fence: + +```yaml +Some config goes here. +``` + +## Example input + +{{< agent-config type="log collection configuration" filename="datadog.yaml" collapsible="true">}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/dashboard_widgets_api.md b/content/en/md_conversion_test_files/uncommon_components/dashboard_widgets_api.md new file mode 100644 index 0000000000000..1d0e26b8c559b --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/dashboard_widgets_api.md @@ -0,0 +1,12 @@ +--- +title: Dashboard Widgets API +widget_type: alert_value +--- + +## Expected .md output + +This shortcode generates tabs and tables, which can be processed the same as any other tabs and tables. + +## Example input + +{{< dashboards-widgets-api >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md b/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md new file mode 100644 index 0000000000000..e9f2c26bba2dd --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md @@ -0,0 +1,15 @@ +--- +title: Expression Language Evaluator +--- + +## Expected .md output + +A placeholder is inserted, like this: + +[INTERACTIVE DEMO OF `matches(\"Hello\", \"^H.*o$\")`] + +## Example input + +This is a test of the expression language evaluator: + +{{< expression-language-evaluator expression="matches(\"Hello\", \"^H.*o$\")" >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/header_list.md b/content/en/md_conversion_test_files/uncommon_components/header_list.md new file mode 100644 index 0000000000000..640a6f1b6f77a --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/header_list.md @@ -0,0 +1,18 @@ +--- +title: Header List +--- + +## Expected .md output + +A list of links. If the header is present, it introduces the list: + +Some header: +- Link one +- Link two + +## Example input + +{{< header-list header="Section title" >}} + {{< nextlink href="link/here" >}}Link one{{< /nextlink >}} + {{< nextlink href="link/here" >}}Link two{{< /nextlink >}} +{{< /header-list >}} \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/icon.md b/content/en/md_conversion_test_files/uncommon_components/icon.md new file mode 100644 index 0000000000000..b1dee9f87f897 --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/icon.md @@ -0,0 +1,11 @@ +--- +title: Icon +--- + +## Expected .md output + +A placeholder: `[ICON: some-icon-name]` + +## Example input + + \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/integration_count.md b/content/en/md_conversion_test_files/uncommon_components/integration_count.md new file mode 100644 index 0000000000000..37fac2cf684b4 --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/integration_count.md @@ -0,0 +1,11 @@ +--- +title: Integration count +--- + +## Expected .md output + +A placeholder is used: `[INTEGRATION COUNT PLACEHOLDER]`. + +## Integration count + +Datadog has over {{< translate key="integration_count" >}} integrations. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/kbd.md b/content/en/md_conversion_test_files/uncommon_components/kbd.md new file mode 100644 index 0000000000000..2e22f909bbfb4 --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/kbd.md @@ -0,0 +1,11 @@ +--- +title: kbd +--- + +## Expected .md output + +The `kbd` is replaced with **bold** markers. + +## Example + +To open the Event Management page from Datadog's global search, press Cmd/Ctrl + K and search for `event explorer`. \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/math.md b/content/en/md_conversion_test_files/uncommon_components/math.md new file mode 100644 index 0000000000000..3b14bf39738ac --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/math.md @@ -0,0 +1,12 @@ +--- +title: Math +--- +{{< jqmath-vanilla >}} + +## Expected .md output + +The literal contents are wrapped in a code fence labeled `jqmath`. + +## Example input + +$$(\text"long window error rate" / {1 - \text"SLO target"} ≥ \text"burn rate threshold") ∧ (\text"short window error rate" / {1 - \text"SLO target"} ≥ \text"burn rate threshold") = \text"ALERT"$$ \ No newline at end of file diff --git a/content/en/md_conversion_test_files/uncommon_components/permissions.md b/content/en/md_conversion_test_files/uncommon_components/permissions.md new file mode 100644 index 0000000000000..e08033b0fb91a --- /dev/null +++ b/content/en/md_conversion_test_files/uncommon_components/permissions.md @@ -0,0 +1,11 @@ +--- +title: Permissions +--- + +## Expected .md output + +This generates tables, so it can be processed the same as any other set of tables. + +## Example input + +{{% permissions %}} \ No newline at end of file From 707c0af98cd0fc499bd1650bb7bbda0c53a87438 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 16:04:39 -0500 Subject: [PATCH 02/12] Use tags instead of start/stop strings to support OOTB machine parseability --- .../en/md_conversion_test_files/common_components/alert.md | 2 +- .../md_conversion_test_files/common_components/callouts.md | 4 ++-- .../common_components/collapsible_sections.md | 2 +- .../common_components/images_and_videos.md | 2 +- .../common_components/programming_lang_wrapper.md | 5 +---- .../en/md_conversion_test_files/common_components/tabs.md | 5 +++-- .../uncommon_components/expression_language_evaluator.md | 4 +--- .../en/md_conversion_test_files/uncommon_components/icon.md | 2 +- .../uncommon_components/integration_count.md | 2 +- 9 files changed, 12 insertions(+), 16 deletions(-) diff --git a/content/en/md_conversion_test_files/common_components/alert.md b/content/en/md_conversion_test_files/common_components/alert.md index ac37331eee4c7..9d6f6246edafb 100644 --- a/content/en/md_conversion_test_files/common_components/alert.md +++ b/content/en/md_conversion_test_files/common_components/alert.md @@ -4,7 +4,7 @@ title: Alert ## Expected .md output -Each alert is bordered with `[BEGIN ALERT]` and `[END ALERT]`. For example, `[BEGIN INFO ALERT]`. +Each alert is enclosed in `{% alert %}` and `{% /alert %}` tags, with a `level` attribute. ### Info diff --git a/content/en/md_conversion_test_files/common_components/callouts.md b/content/en/md_conversion_test_files/common_components/callouts.md index 08f450c05234c..895e99320169e 100644 --- a/content/en/md_conversion_test_files/common_components/callouts.md +++ b/content/en/md_conversion_test_files/common_components/callouts.md @@ -4,8 +4,8 @@ title: Callouts ## Expected .md output -- Each callout is marked by `[BEGIN CALLOUT]` and `[END CALLOUT]`. -- Any attributes, such as the title or the URL, are included in the box contents: +- Each callout is enclosed in `{% callout %}` and `{% /callout %}` tags. +- Any attributes, such as the title or the URL, are also included in the box contents: - The title is a heading at the top of the box. - The URL is included with verbiage at the bottom like "Visit this URL: ". diff --git a/content/en/md_conversion_test_files/common_components/collapsible_sections.md b/content/en/md_conversion_test_files/common_components/collapsible_sections.md index d887340ea939b..a5ab5cca11a00 100644 --- a/content/en/md_conversion_test_files/common_components/collapsible_sections.md +++ b/content/en/md_conversion_test_files/common_components/collapsible_sections.md @@ -4,7 +4,7 @@ title: Collapsible Sections ## Expected .md output -Each section begins and ends with a box marker: `[BEGIN BOX]` and `[END BOX]`. +- Each section is enclosed in `{% collapsible-section %}` and `{% /collapsible-section %}` tags. Any attributes, like `title`, are included in the tag. ## Example inputs diff --git a/content/en/md_conversion_test_files/common_components/images_and_videos.md b/content/en/md_conversion_test_files/common_components/images_and_videos.md index d71d506766ddf..1c2c8ab403c6b 100644 --- a/content/en/md_conversion_test_files/common_components/images_and_videos.md +++ b/content/en/md_conversion_test_files/common_components/images_and_videos.md @@ -4,7 +4,7 @@ title: Images and Videos ## Expected .md output -A placeholder including relevant information about the asset, such as `[IMAGE src="some/src/path" alt="some alt text"]`. +An easily readable tag is used for each one, such as `{% image src="path/to/image" %}`, with any available attributes. ## Example inputs diff --git a/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md b/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md index 1388faec45b4f..e840b1db05f49 100644 --- a/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md +++ b/content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md @@ -4,10 +4,7 @@ title: Programming lang wrapper ## Expected .md output -These are treated as tabs: - -- Each section starts with `[BEGIN TAB]` and end with `[END TAB]`. -- Each section includes its label at the top (for example, "Python"), formatted as a heading. +These are treated as tabs (see `tabs.md`). ## Example input diff --git a/content/en/md_conversion_test_files/common_components/tabs.md b/content/en/md_conversion_test_files/common_components/tabs.md index 7125df36bac51..d1b2cb0f01f65 100644 --- a/content/en/md_conversion_test_files/common_components/tabs.md +++ b/content/en/md_conversion_test_files/common_components/tabs.md @@ -4,8 +4,9 @@ title: Tabs ## Expected .md output -- Each tab starts with `[BEGIN TAB]` and end with `[END TAB]`. -- Each tab includes its label at the top (for example, "Python"), formatted as a heading. +- Each tab set is wrapped in `{% tabs %}` and `{% /tabs %}` tags. +- Each tab is enclosed in `{% tab %}` and `{% /tabs %}` tags. +- Each tab includes its label at the top (for example, "Python"), formatted as a heading of the appropriate level based on context. If no heading levels are left, bold is used, on its own line. ## Example input diff --git a/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md b/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md index e9f2c26bba2dd..d3b08bfb4023b 100644 --- a/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md +++ b/content/en/md_conversion_test_files/uncommon_components/expression_language_evaluator.md @@ -4,9 +4,7 @@ title: Expression Language Evaluator ## Expected .md output -A placeholder is inserted, like this: - -[INTERACTIVE DEMO OF `matches(\"Hello\", \"^H.*o$\")`] +A tag is inserted: `{% interactive-demo for-expression="some expression" /%}` ## Example input diff --git a/content/en/md_conversion_test_files/uncommon_components/icon.md b/content/en/md_conversion_test_files/uncommon_components/icon.md index b1dee9f87f897..063e043331386 100644 --- a/content/en/md_conversion_test_files/uncommon_components/icon.md +++ b/content/en/md_conversion_test_files/uncommon_components/icon.md @@ -4,7 +4,7 @@ title: Icon ## Expected .md output -A placeholder: `[ICON: some-icon-name]` +A self-closing tag: `{% icon name="some-icon-name" %}` ## Example input diff --git a/content/en/md_conversion_test_files/uncommon_components/integration_count.md b/content/en/md_conversion_test_files/uncommon_components/integration_count.md index 37fac2cf684b4..ad12c48d96b38 100644 --- a/content/en/md_conversion_test_files/uncommon_components/integration_count.md +++ b/content/en/md_conversion_test_files/uncommon_components/integration_count.md @@ -4,7 +4,7 @@ title: Integration count ## Expected .md output -A placeholder is used: `[INTEGRATION COUNT PLACEHOLDER]`. +A self-closing tag: `{% integration-count /%}`. ## Integration count From 5d128ecc3688bf512d2d88977adaf882d049e3ff Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 16:11:23 -0500 Subject: [PATCH 03/12] Update plain_markdown.md --- .../common_components/plain_markdown.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/en/md_conversion_test_files/common_components/plain_markdown.md b/content/en/md_conversion_test_files/common_components/plain_markdown.md index 68a20e3138309..d9e125109111e 100644 --- a/content/en/md_conversion_test_files/common_components/plain_markdown.md +++ b/content/en/md_conversion_test_files/common_components/plain_markdown.md @@ -4,7 +4,9 @@ title: Plain Markdown Elements ## Expected .md output -- Most of this should remains unchanged, or uses a format that does not meaningfully differ from its original form. (Some spacing changes can be difficult to avoid.) +- Most of this should remains unchanged, or uses a format that does not meaningfully differ from its original form. + - Some spacing changes can be difficult to avoid. + - OOTB Markdoc does not support description lists, but a similar structure can be used. (Longer term, Markdoc can be patched to support it, as we've already done with Cdocs, but it introduces complexity that we probably don't want to deal with at this stage.) - In some cases, content may be slightly optimized for agents (for example, links will become inline). ## Headings @@ -72,9 +74,6 @@ Resource `clusterChecksRunner.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution` : Required. A list of node selector terms. The terms are ORed. -`site` -: Set the site of the Datadog intake for Agent data: {{< region-param key="dd_site" code="true" >}}. Defaults to `datadoghq.com`. - [1]: https://www.google.com [2]: https://astro.build/ From 5f72d638cf8f5f67a10cb8bbd4902168b853fbfe Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 16:27:37 -0500 Subject: [PATCH 04/12] Use a heading to introduce further reading, for machine parseability --- .../common_components/further_reading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/md_conversion_test_files/common_components/further_reading.md b/content/en/md_conversion_test_files/common_components/further_reading.md index 53e829783ff79..0c5ee3a039c47 100644 --- a/content/en/md_conversion_test_files/common_components/further_reading.md +++ b/content/en/md_conversion_test_files/common_components/further_reading.md @@ -11,7 +11,7 @@ further_reading: ## Expected .md output -A list of links, introduced by the text "Further reading:". +A list of links, introduced by the "Further Reading" heading. ## Example input From e03dcd7bce1492f420426f4f77582f0f31cdbefc Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 16:33:00 -0500 Subject: [PATCH 05/12] Use an alert tag for site-region, for machine parseability --- .../common_components/plain_markdown.md | 2 +- .../common_components/region_shortcodes.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/content/en/md_conversion_test_files/common_components/plain_markdown.md b/content/en/md_conversion_test_files/common_components/plain_markdown.md index d9e125109111e..9c8b27ffe6db4 100644 --- a/content/en/md_conversion_test_files/common_components/plain_markdown.md +++ b/content/en/md_conversion_test_files/common_components/plain_markdown.md @@ -4,7 +4,7 @@ title: Plain Markdown Elements ## Expected .md output -- Most of this should remains unchanged, or uses a format that does not meaningfully differ from its original form. +- Most of this should remains unchanged, or uses a format that does not meaningfully differ from the original. - Some spacing changes can be difficult to avoid. - OOTB Markdoc does not support description lists, but a similar structure can be used. (Longer term, Markdoc can be patched to support it, as we've already done with Cdocs, but it introduces complexity that we probably don't want to deal with at this stage.) - In some cases, content may be slightly optimized for agents (for example, links will become inline). diff --git a/content/en/md_conversion_test_files/common_components/region_shortcodes.md b/content/en/md_conversion_test_files/common_components/region_shortcodes.md index 9f5af356ea76e..6911586e64952 100644 --- a/content/en/md_conversion_test_files/common_components/region_shortcodes.md +++ b/content/en/md_conversion_test_files/common_components/region_shortcodes.md @@ -6,7 +6,8 @@ title: Region Shortcodes ### Expected .md output -The contents are enclosed in `[BEGIN CONTENT FOR REGIONS "ap1", "gov"]` and `[END CONTENT FOR REGIONS "ap1", "gov"]`. +- The contents are enclosed in a `{% alert level="info" %}` tag. +- The alert contents include a heading or similar content establishing the context of the alert (e.g., "Alert for users on `ap1.datadoghq.com`"). ### Example input From fb0b6ad4ce9fac7e966cef231d2014a9dec95c58 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 16:33:59 -0500 Subject: [PATCH 06/12] Use a tag for the region param shortcode in copy, for machine parseability --- .../common_components/region_shortcodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/md_conversion_test_files/common_components/region_shortcodes.md b/content/en/md_conversion_test_files/common_components/region_shortcodes.md index 6911586e64952..6c87c6fbcc988 100644 --- a/content/en/md_conversion_test_files/common_components/region_shortcodes.md +++ b/content/en/md_conversion_test_files/common_components/region_shortcodes.md @@ -22,7 +22,7 @@ This paragraph only appears if the user has selected US or AP1 from the Site Sel A placeholder: - `` in code. -- `[USER'S DATADOG SITE]` in copy. +- `{% user-datadog-site /%}` in copy. ### Example inputs From 7c982033f86bd071caefcd46600f003589887602 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 16:35:54 -0500 Subject: [PATCH 07/12] Add examples of underscore bolding/italicizing --- .../common_components/plain_markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/md_conversion_test_files/common_components/plain_markdown.md b/content/en/md_conversion_test_files/common_components/plain_markdown.md index 9c8b27ffe6db4..85aac5b006c06 100644 --- a/content/en/md_conversion_test_files/common_components/plain_markdown.md +++ b/content/en/md_conversion_test_files/common_components/plain_markdown.md @@ -29,7 +29,7 @@ Some text. ## Inline text formatting -You can *italicize* text, or **bold** it. +You can *italicize* text, or **bold** it. You can also use underscores to _italicize_ or __bold__ it. Text can also be formatted as a [plain link][1], **[bold link][1]**, or *[italic link][1]*. From 0c9f87839246fef413d9226a35d8cf63f5948ab0 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Tue, 19 Aug 2025 17:17:34 -0500 Subject: [PATCH 08/12] Delete README, so context isn't being updated in two places --- content/en/md_conversion_test_files/README.md | 24 ------------------- 1 file changed, 24 deletions(-) delete mode 100644 content/en/md_conversion_test_files/README.md diff --git a/content/en/md_conversion_test_files/README.md b/content/en/md_conversion_test_files/README.md deleted file mode 100644 index b13b5a6a77db7..0000000000000 --- a/content/en/md_conversion_test_files/README.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Plaintext Markdown Spec ---- - -## What is this? - -This folder contains a listing of the components used on the docs site, and a description of their desired output format in the plaintext files generated for AI agents. - -The HTML compiled from these files will be used as the test input HTML for the Markdown generator job. - -## Where can I learn more? - -1. Read [Datadog Docs for AI Agents](https://docs.google.com/document/d/1t48N0uDJElMP_228n2bIYi_cUIj_xMOKjdHuh1Z4rMg), which attempts to summarize the problem space and why this is important. -2. Ask Jen Gilbert. - -## Disclaimer - -Everything described here is *probably* possible based on the technical context and existing libraries we have so far, but it's not *guaranteed* to be possible until the docs are migrated to Markdoc. - -If you'd like to follow along with changes in the spec, Jen will keep this PR up to date, with clear commit messages about what changed. - -## Feedback is welcome! - -Jen took her best shot at these, but she's not attached to any of it. Comment away! \ No newline at end of file From 98af04a21db16a1b0c06f2fee68e919a69d25e9c Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Wed, 20 Aug 2025 08:56:22 -0500 Subject: [PATCH 09/12] Fix typo --- .../common_components/plain_markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/md_conversion_test_files/common_components/plain_markdown.md b/content/en/md_conversion_test_files/common_components/plain_markdown.md index 85aac5b006c06..5ec91cccfbdda 100644 --- a/content/en/md_conversion_test_files/common_components/plain_markdown.md +++ b/content/en/md_conversion_test_files/common_components/plain_markdown.md @@ -4,7 +4,7 @@ title: Plain Markdown Elements ## Expected .md output -- Most of this should remains unchanged, or uses a format that does not meaningfully differ from the original. +- Most of this remains unchanged, or uses a format that does not meaningfully differ from the original. - Some spacing changes can be difficult to avoid. - OOTB Markdoc does not support description lists, but a similar structure can be used. (Longer term, Markdoc can be patched to support it, as we've already done with Cdocs, but it introduces complexity that we probably don't want to deal with at this stage.) - In some cases, content may be slightly optimized for agents (for example, links will become inline). From d3089d658cdebac6939e12887720f5fa509590fd Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Fri, 22 Aug 2025 13:52:32 -0500 Subject: [PATCH 10/12] Use backticks for kbd contents instead of bold --- content/en/md_conversion_test_files/uncommon_components/kbd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/md_conversion_test_files/uncommon_components/kbd.md b/content/en/md_conversion_test_files/uncommon_components/kbd.md index 2e22f909bbfb4..9c8fc72c1cffc 100644 --- a/content/en/md_conversion_test_files/uncommon_components/kbd.md +++ b/content/en/md_conversion_test_files/uncommon_components/kbd.md @@ -4,7 +4,7 @@ title: kbd ## Expected .md output -The `kbd` is replaced with **bold** markers. +The text contents of the `kbd` tag are in backticks (for example, `Cmd`). ## Example From cddc29ea15ad8faaaba8e1b8107103c74a960775 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Fri, 22 Aug 2025 13:56:20 -0500 Subject: [PATCH 11/12] Wrap any raw table HTML in a raw_html tag --- content/en/md_conversion_test_files/common_components/tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/md_conversion_test_files/common_components/tables.md b/content/en/md_conversion_test_files/common_components/tables.md index 5993cf5bc30df..a503a88bc519a 100644 --- a/content/en/md_conversion_test_files/common_components/tables.md +++ b/content/en/md_conversion_test_files/common_components/tables.md @@ -32,7 +32,7 @@ A key-value list for each table row: Both of these should be included: - Whatever the generator can safely derive from the table, in "key-value list" form, with a disclaimer that the data may be incomplete. -- The raw HTML contents, for further reference. +- For further reference, the raw HTML contents, wrapped in a `{% raw_html %}` tag. ### Example input From 0bd2aebc333cfd34379de0437dbeb2d6e1975a41 Mon Sep 17 00:00:00 2001 From: Jen Gilbert Date: Fri, 22 Aug 2025 14:07:49 -0500 Subject: [PATCH 12/12] Output plain Markdown tables instead of structured data when handling tables --- .../common_components/tables.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/content/en/md_conversion_test_files/common_components/tables.md b/content/en/md_conversion_test_files/common_components/tables.md index a503a88bc519a..5222efea45fa7 100644 --- a/content/en/md_conversion_test_files/common_components/tables.md +++ b/content/en/md_conversion_test_files/common_components/tables.md @@ -6,15 +6,7 @@ title: Tables ### Expected .md output -A key-value list for each table row: - -- Name: Jen - Country: USA - Has dog?: Yes - -- Name: Kari - Country: Canada - Has dog?: No +No changes expected, beyond some spacing changes that don't impact the parseability of the content. The rendering library uses a uniform format for outputting Markdown tables, which sometimes won't match the original markup exactly. ### Example input @@ -31,7 +23,7 @@ A key-value list for each table row: Both of these should be included: -- Whatever the generator can safely derive from the table, in "key-value list" form, with a disclaimer that the data may be incomplete. +- A plain Markdown table rendered to the best of our ability, with a preference for omitting rows vs. accidentally changing their meaning. - For further reference, the raw HTML contents, wrapped in a `{% raw_html %}` tag. ### Example input