cloudflare / cloudflare/developer-platform

Markdown for Agents: `<pre>` code blocks lose their fencing, so code is emitted as prose

Open
#37 1 comment 0 reactions 1 assignee Claimed by @celso View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.