[RFC, DO NOT MERGE] Spec for generating plaintext .md files for AI agents #31181
Conversation
📝 Documentation Team Review RequiredThis pull request requires approval from the @DataDog/documentation team before it can be merged. Please ensure your changes follow our documentation guidelines and wait for a team member to review and approve your changes. |
content/en/md_conversion_test_files/common_components/further_reading.md
Outdated
Show resolved
Hide resolved
content/en/md_conversion_test_files/common_components/images_and_videos.md
Outdated
Show resolved
Hide resolved
content/en/md_conversion_test_files/common_components/programming_lang_wrapper.md
Outdated
Show resolved
Hide resolved
content/en/md_conversion_test_files/common_components/region_shortcodes.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Expected .md output | ||
|
|
||
| Each alert is enclosed in `{% alert %}` and `{% /alert %}` tags, with a `level` attribute. |
There was a problem hiding this comment.
@onemec In cases like this, do you want me to also echo the attributes as plaintext content, like having "Info alert" as the bolded first line or something? Or does that get in the way? You can always add it yourself later in parsing as well, but happy to provide it up front if it's useful
content/en/md_conversion_test_files/common_components/plain_markdown.md
Outdated
Show resolved
Hide resolved
content/en/md_conversion_test_files/common_components/tables.md
Outdated
Show resolved
Hide resolved
| A placeholder: | ||
|
|
||
| - `<YOUR_DATADOG_SITE>` in code. | ||
| - `{% user-datadog-site /%}` in copy. |
There was a problem hiding this comment.
This one is tricky, we could also just say "your Datadog site" in plain text. But I wasn't sure if that would cause odd results sometimes in the content.
There was a problem hiding this comment.
This is so cool, Jen! Thank you for putting this together. I left a handful of small comments to consider, which don't necessarily have to be addressed in the initial iteration.
Outside of the specific transformations, I was curious if you have any thoughts on how to handle nested components? For example, alerts or code blocks inside of tabs, etc. It's probably straightforward in most cases, but it could be worth defining rules to disallow certain nesting behavior/defining fallbacks?
content/en/md_conversion_test_files/common_components/tables.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Expected .md output | ||
|
|
||
| The `kbd` is replaced with **bold** markers. |
There was a problem hiding this comment.
This definitely works, but I think it would be slightly better to represent keys with backticks rather than bold, since that is more common for keys and commands in Markdown.
Spec for generating machine-parseable .md files for AI agents
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 content files generated for AI agents. These are plain Markdown where possible, with a few simple tags (like
alert) to support the machine parseability required for our internal docs ingestion processes.The HTML compiled from these files will be used as the test input HTML for the Markdown generator job.
Where can I learn more?
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 is not attached to any of this. Comment away!
Collaborators
Thanks to Oliver Nemec for revising this spec to be compatible with internal ingestion processes.