Docs / Using the editor
Embeds
Show diagrams where people already read: READMEs, wikis, docs sites and blog posts.
On this page
There are two kinds of embed: a static image for READMEs and other Markdown, and an interactive viewer for web pages.
README embeds
A README embed is an SVG image of a saved diagram that links to the full diagram. It updates whenever you edit the diagram, so the picture in your README never goes stale.
- Save the diagram to your account. See Accounts and saving.
- Make sure it is unlisted, not private.
- Choose Copy README embed in the Share menu.
- Paste the Markdown into your README, wiki or docs.
The copied Markdown looks like this:
[](https://volley.sh/d/abc123)Options
| Address | Gives |
|---|---|
/d/<id>.svg | The diagram in the light appearance |
/d/<id>.svg?theme=dark | The dark appearance |
To follow the reader's light or dark preference on GitHub, use a picture element with both:
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://volley.sh/d/abc123.svg?theme=dark">
<img alt="Fetch invoices" src="https://volley.sh/d/abc123.svg">
</picture>Things to know
- Images refresh within about a minute of an edit. Some sites, including GitHub, cache images for longer.
- Private diagrams do not render. The address returns a small "Volley diagram not found" image instead.
- Images on Free carry a small "Made with Volley" badge. Pro removes it, and existing embeds pick up the change within about a minute.
- Loading an embed does not count as a view of the diagram.
- The image shows arrows and payload chips but not icons or inline payloads. For the full experience, readers click through.
Interactive embeds
The interactive embed is the Volley viewer in an iframe. Readers can select arrows, open the inspector, show payloads, collapse lanes and open the diagram in Volley. It has no editor and saves nothing.
Choose Copy embed code in the Share menu. You get an iframe like this:
<iframe src="https://volley.sh/d/abc123?embed" title="Fetch invoices" width="100%" height="520" style="border:0" loading="lazy"></iframe>For a saved, non-private diagram the embed shows the latest saved version. For anything else it embeds a snapshot of the diagram as it is now.
Options
Add these to the address in the src:
| Option | Effect |
|---|---|
?embed | Required. Shows the viewer instead of the editor. |
theme=dark, theme=light, theme=system | The appearance. Light is the default; system follows the reader's setting. |
payloads=1 | Starts with payloads shown inline |
For example: https://volley.sh/d/abc123?embed&theme=system&payloads=1.
In the embed
- Click an arrow to open the inspector, and press Esc to close it.
- Use a lane's menu to collapse or expand lanes, or Collapse quiet lanes when the diagram is wide.
- Turn Show payloads on and off.
- Open in Volley opens the diagram in the editor in a new tab.
- In narrow iframes, the embed fits lanes automatically and offers the steps view, as on a phone.
Change the iframe's height to suit the diagram. Wide diagrams scroll sideways inside the frame.