QR codes in markdown

The one-liner

![QR code for the demo site](https://useqr.app/q/https%3A%2F%2Fexample.com.png)

The /q/{data}.png path form exists precisely for this: the payload is the path, the extension picks the format, and there is no query string to fight with markdown parsers. /q/hello.svg works the same way. It is the shortest route from "URL in a README" to "phone pointing at a laptop screen" — install links for mobile apps, demo URLs, conference slides written in markdown, a repo's sponsor link.

Everything about the underlying service — determinism, immutability, no key — is on the keyless API page.

Encode the payload

Inside a path, percent-encoding is not optional. /, ?, & and # all have meanings you do not want:

<!-- wrong: the slashes make this a different path -->
![QR](https://useqr.app/q/https://example.com/sale.png)

<!-- right -->
![QR](https://useqr.app/q/https%3A%2F%2Fexample.com%2Fsale.png)

Any language's encodeURIComponent equivalent produces the right string, as does one curl call if you want to eyeball the result first. Simple payloads with no reserved characters — hello, a plain domain — can go in bare.

GitHub READMEs specifically

Two GitHub behaviours worth knowing:

• Images are proxied. GitHub rewrites external image URLs through its camo proxy and caches them. That is fine here — the API's responses are deterministic and marked immutable, so what camo caches is what you meant, forever.
• Markdown cannot size images, but GitHub renders raw <img> tags, which can:

<img src="https://useqr.app/q/https%3A%2F%2Fexample.com.png"
     width="180" alt="QR code linking to example.com" />

Around 160–200 px displays small enough not to dominate the page while remaining scannable off a typical laptop screen — codes on screens have their own considerations, covered in scanning a QR code off a monitor.

Docs generators (Docusaurus, MkDocs, mdBook, Sphinx with MyST) all render standard image syntax, so the same line works unchanged; prefer the .svg form there, since docs sites zoom and rescale.

When to vendor the image instead

Hotlinking is one line, but commit the actual file when:

• the docs must render offline or air-gapped (internal wikis, vendored docs, PDFs built in CI without network);
• your organisation's policy forbids third-party image loads;
• you want the repo to be self-contained on principle — a fair position.

Vendoring is one command, then a relative link:

curl -o docs/img/demo-qr.png "https://useqr.app/q/https%3A%2F%2Fexample.com.png"

![QR code for the demo site](img/demo-qr.png)

Since static codes are deterministic, the committed file never goes stale unless the destination URL itself changes — and if you control that URL's content, it never has to. Caching trade-offs of hotlink vs vendor at scale are discussed in caching and CDN strategy for QR images.

Alt text

Screen readers cannot scan. Write alt text that names the destination ("QR code linking to the releases page"), and keep the plain hyperlink in the prose nearby, so the code is a convenience rather than the only path.

FAQ

How do I put a QR code in a GitHub README?

Use standard image syntax with the path-style endpoint: . GitHub proxies and caches it; nothing else is needed.

How do I control the QR code size in markdown?

Markdown itself cannot, but GitHub and most docs sites render raw img tags, so set width there. Around 180 px is a sensible README size.

Should I hotlink or commit the image?

Hotlink for public docs — it is one line and cached immutably. Commit the file for offline, air-gapped or policy-restricted documentation.

Why does my QR markdown link break?

Almost always encoding: slashes, question marks and ampersands in the payload must be percent-encoded when using the /q/ path form.