Put it in a README or a site

An archgram drawing is one SVG file with everything inside it, the font, both themes and the animation. Show it anywhere an image shows.

In a GitHub README#

Link the SVG like any image, by its path in your repository.

![A visit goes through the API to Postgres.](docs/diagrams/linkshort.svg)

The flows play inside the image, with no script, and the drawing follows the reader's light or dark mode. Write alt text that tells the flow in words, since a screen reader reads it in place of the drawing. The agent's report gives you this line, alt text included.

Some places show your README outside the repository, npm among them, and may not find a relative path. A full address works everywhere, as archgram's own README does.

![A visit goes through the API to Postgres.](https://raw.githubusercontent.com/you/your-repo/main/docs/diagrams/linkshort.svg)

Follow GitHub's theme#

One SVG follows the reader's system. GitHub lets a reader pick a theme that differs from their system's. To follow GitHub's choice instead, draw a file for each theme.

npm exec -- archgram build docs/diagrams/linkshort.archgram.yaml --split-themes

pnpm exec archgram build docs/diagrams/linkshort.archgram.yaml --split-themes

yarn archgram build docs/diagrams/linkshort.archgram.yaml --split-themes

That writes linkshort.light.svg and linkshort.dark.svg from one layout. Let the page pick.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/linkshort.dark.svg">
  <img src="docs/diagrams/linkshort.light.svg" alt="A visit goes through the API to Postgres.">
</picture>

On a site with its own theme switch, show the file that matches the page, as this site does.

One theme only#

For a page that is always light or always dark, draw that theme alone.

npm exec -- archgram build docs/diagrams/linkshort.archgram.yaml --theme dark

pnpm exec archgram build docs/diagrams/linkshort.archgram.yaml --theme dark

yarn archgram build docs/diagrams/linkshort.archgram.yaml --theme dark

On a docs site or a blog#

Use an <img>, or your site's Markdown image. Give it the drawing's width and height, so the page keeps its place while it loads. archgram build prints both.

wrote docs/diagrams/linkshort.svg (704 × 146 px, left to right)

<img src="/diagrams/linkshort.svg" alt="A visit goes through the API to Postgres." width="704" height="146">

Keep the text readable#

A page shows a wide drawing smaller, and its text shrinks with it. archgram keeps a drawing's text readable in a GitHub README, which shows an image about 880 px wide, and warns when a drawing is wider than that allows.

archgram: warning: docs/diagrams/architecture.archgram.yaml: the drawing is 2267 px wide, wider than the 1300 px a README on GitHub shows at a readable size; write `direction: down`, which draws it 249 px wide, or split it in two

If the diagram is shown somewhere narrower, say how wide in the spec, in CSS pixels, and archgram measures against that place instead.

shownWidth: 674

The widest readable drawing is then shownWidth × 1300 / 880, 996 px for 674. A diagram shown in two places takes the narrower. direction: auto chooses the direction against the same width. The warning never stops a drawing, so you decide.

The font#

archgram embeds Geist, the font it measured the text with, so the drawing looks the same everywhere. --system-font leaves the text to the reader's font instead, which makes the file smaller, but a wider font can crowd or overflow a card.

The credit#

A drawing carries a small "by archgram" in its bottom-right corner, which a screen reader skips. credit: false in the spec leaves it out.