cloudflare / cloudflare/nimbus

Diagram Markdown output should use its fallback instead of UI and SVG text

Open Beginner friendly
#123 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.