Embeds: Putting a Live NitroIDE Playground Inside Your Docs
Every tutorial has the same weak spot: the code sample. A static block shows what the code looks like. It cannot show what the code does. The reader has to copy it, open an editor, paste it, and run it — and every step in that chain is a step where a reader leaves.
A month ago I wrote about NitroIDE's share engine: the Share button compresses an entire workspace into a ?code= URL parameter, and opening that link rebuilds the workspace locally in the reader's browser. Nothing is uploaded to a server. That post was about sending code to one person. This one is about the layer on top of it: embedding that workspace inside a page, so the reader never has to leave the tutorial at all.
One parameter turns a share link into an embed
Take any NitroIDE share URL and add ?embed=1 to it. That is the whole API:
<iframe src="https://nitroide.com/tools/codebox.html?embed=1&code=YOUR_SHARE_CODE" width="100%" height="500" frameborder="0"></iframe>The embed loads a stripped-down, read-only viewer. The full IDE chrome is gone — no file explorer, no console panel, no settings menus. What remains is the two things a reader actually needs: the editor and the live preview, side by side. The reader sees the code and its output in the same frame, on the same page, with nothing to install and no account to create.
Read-only is a deliberate choice, not a missing feature. A tutorial embed is not a workspace; it is a demonstration. If the reader could edit the code in place, every edit would be a fork of the author's example with no way back — and the next reader would see someone else's experiment, not the tutorial. So the embed shows, and the escape hatch handles editing: every embed carries a footer link reading "Built with NitroIDE — open & edit". One click opens the exact workspace in the full editor, where the reader can change anything. Show first, edit second, and never confuse the two.
Where this actually belongs
The honest answer is: anywhere that renders an iframe and where the reader is there to learn. Blog posts, documentation pages, tutorial sites, course material — anywhere a code sample currently sits as a dead block.
It does not belong in a GitHub README. GitHub strips iframes from rendered Markdown, so an embed pasted into a README renders as nothing. That is what the "Open in NitroIDE" badge is for — a link, not a frame — and knowing which of the two a surface accepts is the difference between an embed that works and one that silently vanishes. If the page cannot render an iframe, do not force the embed in; link out instead.
The second place it belongs is less obvious: your own changelog and release notes. A new feature described in prose is a claim; the same feature embedded as a running demo is evidence. When a release note says "the preview now updates without flicker," an embedded playground running the new behaviour lets the reader verify it in ten seconds instead of trusting the sentence.
The details that make an embed feel native, not bolted on
A bare iframe works. A few attributes make it feel like part of the page:
width="100%"and a fixed height around 500px. The embed is a window into a workspace, and a window needs a predictable frame. Let it fill the content column and keep the height tall enough that the preview is readable without scrolling inside a scrolling page.loading="lazy"on embeds below the fold. A tutorial with five demos should not load five editors before the reader reaches the first one. Lazy loading defers each embed until it scrolls into view.- A
titleattribute on the iframe. It costs nothing and it is what a screen reader announces; "Live demo: responsive card layout" is a better experience than an unnamed frame. - One demo per concept. An embed is a heavyweight element — a whole editor and a live preview. Three embeds proving the same point are two embeds too many; one well-chosen demo per idea keeps the page fast and the argument sharp.
None of these are NitroIDE features. They are the hosting page's job, and they are the difference between an embed that feels like part of the tutorial and one that feels pasted in.
The limits, stated plainly
An embed inherits every limit of the share link it is built on. The workspace travels inside the URL itself, compressed into the ?code= parameter, so a very large project makes a very long URL. For a tutorial demo — a handful of files, a single concept — that is never a problem. For a full application, it is: use ZIP export for the project and embed a small, focused demo of the idea instead. The embed is for the example, not the app.
The second limit comes from the preview's sandbox. NitroIDE's preview runs in a sandboxed iframe with an opaque origin, which is what keeps code in a shared link from touching the reader's saved projects. The tradeoff is that localStorage, sessionStorage, and cookies are unavailable inside the preview — and in Safari, touching them throws a SecurityError. Demo code that reads localStorage unguarded will crash inside the embed while working fine in a normal tab. Wrap storage access in try/catch in any code you plan to embed, and the same demo runs everywhere.
The third limit is the read-only viewer itself. It hides the console, so a demo whose point is console output — logging, errors, debugging — loses its punchline inside an embed. That is a real constraint, and the honest response is to pick the right surface: embed the demos whose output is visual, and link out to the full editor for the ones whose output lives in the console.
Why this matters more than a nicer code block
Syntax highlighting made code readable. Embeds make it runnable, and that is a different category of change. A readable sample asks the reader to trust the author. A runnable sample lets the reader check the author — change a value, watch the preview move, break it, fix it. That is the feedback loop NitroIDE is built around, except now it happens inside someone else's docs, for a reader who never opened the IDE at all.
The embed is also the quietest distribution NitroIDE has. Every embed carries its own attribution in the footer, and every footer click is a reader who arrived at the full editor from inside a tutorial they were already reading — not from a post, not from an ad, from a working demo. That is the growth loop that does not look like a growth loop: make the tool useful inside other people's pages, and let the pages do the talking.
One parameter, one iframe, one running demo where a dead code block used to be. Try it with the docs example above — paste a share code into the snippet, drop it into a page, and the tutorial stops describing the code and starts running it.
Try it
I build NitroIDE — a browser-based IDE where your code never leaves your machine: nitroide.com
⭐ If you enjoyed this, star NitroIDE on GitHub: github.com/nitroideofficial/nitroide
Frequently asked questions
How do you embed a NitroIDE playground in a page?
Take any NitroIDE share URL, add ?embed=1 to it, and drop it in an iframe. It loads a stripped-down, read-only viewer with just the editor and the live preview — no file explorer, console panel, or settings menus.
Why is the embed read-only?
A tutorial embed is a demonstration, not a workspace. If readers could edit in place, the next reader would see someone else's experiment instead of the tutorial. The footer link "Built with NitroIDE — open & edit" opens the exact workspace in the full editor for anyone who wants to change it.
Where should you not use a NitroIDE embed?
GitHub READMEs strip iframes from rendered Markdown, so an embed there renders as nothing — link out with the "Open in NitroIDE" badge instead. And demos whose point is console output lose their punchline, because the embed hides the console; those belong in the full editor.