Skip to content

docs: fix volume-content mermaid diagram rendering - #3626

Open
forrestIsRunning wants to merge 1 commit into
e2b-dev:mainfrom
forrestIsRunning:docs/fix-volume-content-mermaid
Open

docs: fix volume-content mermaid diagram rendering#3626
forrestIsRunning wants to merge 1 commit into
e2b-dev:mainfrom
forrestIsRunning:docs/fix-volume-content-mermaid

Conversation

@forrestIsRunning

Copy link
Copy Markdown

Problem

The Volume content sequence diagram in docs/ARCHITECTURE.md does not render on GitHub:

Parse error on line 12:
... for BYOC teams;<br/>SDK stores it and f
-----------------------^

Mermaid sequence diagrams treat ; as a statement separator (equivalent to a newline). After BYOC teams;, the parser starts a new statement at <br/> and fails. The same diagram also uses HTML &lt; / &gt; for domain placeholders; those are invalid tokens in current Mermaid.

This is a docs-only bug. CONTRIBUTING.md says documentation fixes can skip the issue-first step.

Fix

Use Mermaid entity codes in that sequence diagram, which is the documented way to keep the original text:

character in source
; #59;
< #lt;
> #gt;

The rendered note and api.<domain> placeholders stay the same. Surrounding prose is unchanged.

Diagram after the change (should render below)
sequenceDiagram
    autonumber
    participant U as SDK
    participant API as API
    participant PG as PostgreSQL
    participant VC as volume-content API (belt)

    U->>API: POST /volumes (create) or GET /volumes/{id}
    API->>PG: persist / load volume row
    API->>API: mint JWT (aud = https://api.#lt;domain#gt;)<br/>resolve domain
    API-->>U: { volumeID, name, token, domain? }
    Note over U: domain is returned only for BYOC teams#59;<br/>SDK stores it and falls back to api.#lt;E2B_DOMAIN#gt; otherwise
    U->>VC: /volumecontent/{id}/... at api.#lt;domain#gt;<br/>Authorization: Bearer token
    VC->>VC: verify token (audience must match its own origin)
    VC-->>U: file content
Loading

Validation

  • Reproduced the GitHub parse error against current main
  • Parsed all six diagrams in docs/ARCHITECTURE.md with Mermaid 11.12.0 after the change
  • Docs-only; make test / make lint do not apply

Related: #3621 also addresses the GitHub parse error by escaping the semicolon. This change also replaces the HTML entities so the diagram parses in current Mermaid, not only GitHub's renderer.

GitHub fails to render the Volume content sequence diagram because Mermaid treats ';' as a statement separator and HTML &lt;/&gt; entities as invalid tokens. Use Mermaid entity codes so the note and domain placeholders parse.
@HeyiSun

HeyiSun commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

duplicate with #3621

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants