cloudflare / cloudflare/developer-platform

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

Ouverte
#37 1 commentaire 0 réactions 1 personne assignée Réclamée par @celso Voir sur GitHub
Langage dominant
Aucune donnée de langage
Étoiles
1
Forks
0
Métriques de merge des PR
Aucune PR mergée en 30 j

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.

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.