Emit CommonMark for generated API Explorer pages - #3994
Draft
reakaleek wants to merge 3 commits into
Draft
Conversation
Agents and Accept: text/markdown requests currently receive no readable API Markdown. Write sibling .md files from page models and serve them from preview and static hosts. Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Docs preview (local build)Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3994/ Sample changed pages: |
Agents and OKF consumers need structured page metadata. Write title, description, url, products, type, and resource, and drop authored YAML from child pages. Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Reuse the supplemental frontmatter splitter and limit body description inference to authored child pages. Co-Authored-By: GPT-5.6 Sol <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generated API Explorer pages now write a sibling CommonMark file and serve it through a
.mdsuffix orAccept: text/markdown. Agents and tools can read native API pages without scraping HTML.Affects: API reference, Isolated builds
Why
Local preview and isolated builds publish API HTML only. A request for Markdown on an
/api/doc/URL returns HTML or404. elastic/docs-eng-team#809 needs readable CommonMark next to each generated API page.What
Sibling CommonMark files
Each successful
index.htmlwrite also writes a sibling.mdfile from the page models. Grouping models that render no page still emit no file. The generator does not convert Razor HTML.Preview and static serving
Preview and static hosts serve that file when the path ends with
.mdor whenAcceptpreferstext/markdown. Browser andtext/htmlrequests still receive HTML. Path traversal checks apply to both file types.Alternate link
The API layout emits one
<link rel="alternate" type="text/markdown">in the document head. There is no visible View as Markdown or Copy as Markdown control.Out of scope:
OkfMarkdownExporterstill skips live/api/*links. Productionwww.elastic.costill proxies API pages to bump.sh until the API Explorer cutover.Verify
curl -D - http://localhost:3000/api/doc/docs-builder-elasticsearch.md curl -D - -H 'Accept: text/markdown' http://localhost:3000/api/doc/docs-builder-elasticsearch/ curl -D - http://localhost:3000/api/doc/docs-builder-elasticsearch/operation/operation-async-search-get.mdExpect
200andtext/markdown; charset=utf-8with readable CommonMark. A normal browser request to the HTML URL must still return HTML.Made with Cursor