cloudflare / cloudflare/nimbus
Diagram Markdown output should use its fallback instead of UI and SVG text
- Dominant language
- TypeScript
- Stars
- 984
- Forks
- 34
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 31
Description
## Problem
Nimbus diagrams produce noisy, misleading Markdown when rendered HTML is converted by Markdown for Agents. Diagram controls and SVG labels are concatenated instead of being replaced by a plain-language fallback.
For example:
```text
Choose an instance identity to send a request
ABReset
RequestWORKERRequestWORKERDURABLE OBJECTAROUTEHOOKSSLEEP...
```
This is specific to Nimbus diagrams, not a request for generic MDX component transformation.
## Existing API gap
`DiagramProps` declares `fallback?: string` in `@cloudflare/nimbus-docs/react`, but `DiagramRoot` does not destructure or render the prop. The browser therefore renders only the interactive `.diagram-render` subtree, and HTML-to-Markdown conversion extracts its controls and SVG text.
## Expected behavior
- HTML continues to show the interactive diagram.
- Markdown output for a Nimbus `Diagram` contains only its plain-language fallback.
- Toolbar labels, live status text, duplicated responsive SVG content, and SVG node labels are omitted from Markdown.
- The existing `fallback` prop is implemented and documented for this purpose, or replaced with an equivalent diagram-specific API.
## Example
```tsx
```
The Markdown representation should be only:
```text
A request flows from the client to the Worker, through a Durable Object, and then to the Container.
```
## Version
Observed with `@cloudflare/nimbus-docs` 0.11.0.
Contributor guide
Research direction
Locate the DiagramRoot implementation and the DiagramProps declaration in @cloudflare/nimbus-docs/react; start by tracing how Diagram renders its interactive content and fallback. Ensure the HTML remains interactive while Markdown conversion receives only the plain-language fallback, with controls and SVG text omitted.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- documentation, frontend
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 75/100