Adding an Interactive Demo to GitBook
August 19, 2026
GitBook is a managed documentation platform, and unlike a static site generator you do not control the rendered HTML.
That means arbitrary iframe embedding is restricted in a way it is not on Docusaurus or a self-hosted site, and it is better to know that before designing a docs page around one.
What GitBook supports
GitBook has an embed block that takes a URL and renders a preview or an inline frame for services it recognises, rather than accepting raw HTML you supply.
Whether your demo URL renders as a live frame or a link card depends on what GitBook supports at the time. Test with your actual URL rather than assuming, because this is the sort of thing that changes.
The reliable approach
- Paste the demo URL into an embed block and see what you get. If it renders inline, you are done.
- If it renders as a card, that is still a good outcome -- a titled, clickable card in documentation is not a bad way to link a demo.
- Otherwise use an image and a link. A screenshot of the demo's first step, linked, works everywhere and never breaks.
Make the link do the work
When you cannot embed, the link text carries the whole burden. "Watch the import flow -- about 60 seconds" gets clicked; "Demo" does not.
Say what it shows and roughly how long it takes. In documentation especially, readers are mid-task and deciding whether they can afford the detour.
Consider whether docs are the right home
Documentation readers are usually looking for a specific answer, and a demo is a slower medium than a code block or a numbered list. That does not mean demos do not belong in docs -- it means they belong on the pages where someone is orienting rather than looking something up.
Getting started, migration guides, and any flow that is genuinely hard to describe in prose. Not the reference.
Frequently asked questions
- Can you embed an interactive demo in GitBook?
- Only through GitBook's own embed block, which takes a URL and renders it according to what the platform supports -- you cannot paste arbitrary iframe HTML. Test with your real demo URL, since it may render inline or as a link card.
- What if my demo will not embed in GitBook?
- Use a screenshot of the demo's first step, linked to the hosted demo. It works everywhere, never breaks, and in documentation a well-labelled link performs close to an embed.
- Should demos go in developer documentation at all?
- On orienting pages -- getting started, migration guides, and flows that are hard to describe in prose. Not on reference pages, where readers are looking up a specific answer and a demo is a slower medium than a code block.
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 →