Follow-up to #2289 (serve docs pages as markdown twins). That feature is live and works well for prose pages, but API reference pages (the ones generated by docusaurus-plugin-openapi-docs) have two problems, both stemming from the same root cause — they use a different OpenAPI page layout:
Problem 1: near-empty .md twins
The generated .md twin for an API reference page contains only the one-line description (~39 tokens), while the rendered HTML page is ~14k tokens.
Example: platforms/anchor-platform/api-reference/platform/transactions/get-transaction.md
| Version |
Tokens |
.md twin |
~39 |
| Rendered HTML |
~14,235 |
Root cause: the schema/parameters/response content on API pages is client-rendered (React hydration — the static HTML only contains openapi-skeleton placeholders). Deep schema fields like amount_in, stellar_transaction_id, kind appear zero times in the static HTML, so neither the markdown plugin nor any HTML-scraping approach can capture them. The only complete source of truth is the bundled OpenAPI specs under openapi/.
Problem 2: missing "Open Markdown" button
The markdown plugin injects its button at document.querySelector('article .markdown header'). Normal doc pages have that <header>; API reference pages don't (they render <article> + .theme-doc-markdown.markdown but no <header>), so the injection silently skips and the button never appears.
Proposed fix
- Content: a new postbuild script (
scripts/generate_api_markdown.mjs) that parses the bundled OpenAPI specs and writes complete markdown (method + path, parameters, request body, response schemas) over the near-empty twins under build/**/api-reference/**. Runs before rewrite_md_links.mjs in the postbuild chain. Output-only — never touches HTML or repo sources, idempotent, scoped strictly to API reference paths.
- Button: a small client-side injection scoped to
/api-reference/ routes that adds the same markdown-actions-container button into an element that does exist on API pages, guarded against double-injection so normal pages are unaffected.
Follow-up to #2289 (serve docs pages as markdown twins). That feature is live and works well for prose pages, but API reference pages (the ones generated by
docusaurus-plugin-openapi-docs) have two problems, both stemming from the same root cause — they use a different OpenAPI page layout:Problem 1: near-empty
.mdtwinsThe generated
.mdtwin for an API reference page contains only the one-line description (~39 tokens), while the rendered HTML page is ~14k tokens.Example:
platforms/anchor-platform/api-reference/platform/transactions/get-transaction.md.mdtwinRoot cause: the schema/parameters/response content on API pages is client-rendered (React hydration — the static HTML only contains
openapi-skeletonplaceholders). Deep schema fields likeamount_in,stellar_transaction_id,kindappear zero times in the static HTML, so neither the markdown plugin nor any HTML-scraping approach can capture them. The only complete source of truth is the bundled OpenAPI specs underopenapi/.Problem 2: missing "Open Markdown" button
The markdown plugin injects its button at
document.querySelector('article .markdown header'). Normal doc pages have that<header>; API reference pages don't (they render<article>+.theme-doc-markdown.markdownbut no<header>), so the injection silently skips and the button never appears.Proposed fix
scripts/generate_api_markdown.mjs) that parses the bundled OpenAPI specs and writes complete markdown (method + path, parameters, request body, response schemas) over the near-empty twins underbuild/**/api-reference/**. Runs beforerewrite_md_links.mjsin thepostbuildchain. Output-only — never touches HTML or repo sources, idempotent, scoped strictly to API reference paths./api-reference/routes that adds the samemarkdown-actions-containerbutton into an element that does exist on API pages, guarded against double-injection so normal pages are unaffected.