Can I embed an interactive demo in a GitHub README?

Not as an iframe -- GitHub does not render them. Add it as a link, ideally behind an image so it reads as something clickable, placed directly under the project description and above the badges and install instructions.

What should a demo for an open-source project show?

The output rather than the setup. Nobody is persuaded by an install command, but a real task run through to a result somebody can evaluate answers the question a README struggles with: what does this actually do?

Is a demo worth the maintenance for a side project?

Only if you will keep it current. A demo showing a version two majors behind is worse than none for a technical audience, since they are precisely the people who notice. Record the flow least likely to change if upkeep is a concern.

← Back to blog

Adding an Interactive Demo to Your GitHub README

August 28, 2026

A README has a few seconds to explain a project before the visitor goes back to the search results. Most spend them on a badge row and an install command.

The people who star, fork and adopt a project are the ones who understood it immediately — and understanding software from prose is exactly what people are bad at.

The kind of link a README can carry — click through it without installing anything.

What a README cannot do

Show the tool running without the reader installing it first.
Convey a CLI's output in a way a screenshot of one command does not.
Explain a UI project to somebody who will not clone it to look.
Answer "is this maintained and real?" which a live, current demo answers implicitly.

How to add one

GitHub does not render iframes in a README, so an embed is not an option — a demo goes in as a link, ideally an image link so it reads as something to click.

Put it directly under the one-line description, above the badges and above installation. Anything below the fold is read by people who were already convinced.

What to record for a code project

The output, not the setup. Nobody is persuaded by an install command.
One real task from start to a result somebody can evaluate.
The config file or flags if that is where the power is.
A dashboard or UI, if the project has one -- that is the part a screenshot always undersells.

Keep it current or drop it

A demo showing a version two majors behind is worse for a project than none, because the audience checking it is the audience that notices.

Re-record on releases that visibly change the interface, and if that is more upkeep than the project can support, keep the demo to the one flow least likely to change.

Frequently asked questions

Can I embed an interactive demo in a GitHub README?: Not as an iframe -- GitHub does not render them. Add it as a link, ideally behind an image so it reads as something clickable, placed directly under the project description and above the badges and install instructions.
What should a demo for an open-source project show?: The output rather than the setup. Nobody is persuaded by an install command, but a real task run through to a result somebody can evaluate answers the question a README struggles with: what does this actually do?
Is a demo worth the maintenance for a side project?: Only if you will keep it current. A demo showing a version two majors behind is worse than none for a technical audience, since they are precisely the people who notice. Record the flow least likely to change if upkeep is a concern.

Keep reading

This is what Demorta does

Click through it — the same kind of demo you can record of your own product.

Try it on your own product

Record your first interactive demo free.

Five demos on the free plan, forever. No credit card, no trial countdown, no sales call. Install the Chrome extension, click through your product once, and you have a shareable link in about ten minutes.

Start free →