cloudflare / cloudflare/developer-platform

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

Offen
#37 1 Kommentar 0 Reaktionen 1 zugewiesene Person Beansprucht von @celso Auf GitHub ansehen
Vorherrschende Sprache
Keine Sprachdaten
Sterne
1
Forks
0
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

## 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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.