cloudflare / cloudflare/developer-platform
Markdown for Agents: `<pre>` code blocks lose their fencing, so code is emitted as prose
- Dominant language
- No language data
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Markdown for Agents (MfA) does not preserve code blocks. `
` elements in the source HTML are converted to plain paragraphs in the Markdown output — no fences, no indentation, no language hint. Their inner content is then processed as ordinary inline Markdown.This is a content-fidelity bug rather than a formatting nit, because Markdown assigns meaning to characters that are inert inside a code block. A `#` at the start of a line becomes a heading; `*` and `_` become emphasis. So a Python or shell comment inside a sample is silently promoted to a document heading, and a consumer has no way to tell where code starts or stops.
Reproduces on every Read the Docs-hosted project I've checked, across two different documentation generators (Sphinx and MkDocs Material), so it doesn't look theme-specific.
## Reproduction 1 — Sphinx (docs.ray.io)
```bash
URL="https://docs.ray.io/en/master/ray-core/fault-tolerance.html"# Source HTML: 5
blocks
curl -s "$URL" | grep -o '` (and ``) should emit a fenced code block, with the language taken from the usual class hints where available (`class="language-python"`, `class="highlight-python"`, Pygments' `class="highlight"` wrappers):````
```python
@ray.remote
class Actor:
def read_only(self):
...
```
````Inside the fence, content should be emitted verbatim — no inline-Markdown processing, no link extraction, no escaping.
## Impact
- **Every Read the Docs-hosted project.** MfA is enabled in front of all of them (see readthedocs/readthedocs.org#13054), and technical documentation is largely code.
- **Silent corruption rather than visible breakage.** The prose reads fine, so a consumer has no signal that the code has been mangled. An agent extracting a snippet gets something that looks plausible and doesn't run.
- Same converter appears to back the Browser Rendering `/crawl` API (#13406), so a fix would likely benefit both surfaces.## Related
- cloudflare/workers-sdk#14488 — MfA stripped the trailing slash from the base URL on directory-style pages (fixed 2026-07-07). Same converter, different failure.
- cloudflare/workers-sdk#13406 — Browser Rendering `/crawl`: root-relative image URLs resolved incorrectly.
- cloudflare/cloudflare-docs#31303 — `hostname` option requires a URL.
- readthedocs/readthedocs.org#13054 — the Read the Docs tracking issue for MfA converter bugs; Read the Docs also has a support request open with Cloudflare.Filing here rather than only through Read the Docs' support channel, since cloudflare/workers-sdk#14488 was resolved quickly once it was reported publicly.
Contributor guide
Assessment
This issue has not been assessed yet.