I recently built and deployed a code playground component to render HTML+CSS+JS examples in my blog posts that enhances them with a live preview of how they’d look in tandem. Think of it as a read-only version of CodePen/StackBlitz/CodeSandbox embeds, but 10x cooler because it requires zero JavaScript and it’s built as a shortcode using Hugo’s templating features.
Here’s how the whole thing looks:
<h1>Hello world!</h1>h1 { color: orangered; }console.log("Hello world!");Early on during the implementation, I was thinking about ways to render the live preview of the generated HTML document formed by combining the individual snippets. We can go about it in several ways but I ultimately settled on using iframes since they provide the document a clean and isolated environment to execute in. But, how does one go about adding this generated HTML inside the iframe?
We could write client-side JavaScript and access the iframe’s contentDocument.innerHTML to inject our document string. But I wasn’t satisfied needing JavaScript right away for such a seemingly straightforward functionality — there must be another way to do it within Hugo’s templating system.
One way to resolve this conundrum is by using Data URLs. Modern browsers allow using these special types of URLs where we can (optionally) encode and represent text/binary data as a string with an associated MIME type so that the browser can render the data correctly. For example, try copy pasting the following data URL into your address bar and hit enter:
data:text/html;charset=utf-8,%3Ch1%3EHello%20sunshine!%20☀%EF%B8%8F%3C/h1%3E
This should render “Hello sunshine! ☀️” inside an h1 tag as HTML. Additionally, we can encode the HTML document into Base64 format which makes things a bit more URL-friendly:
data:text/html;charset=utf-8;base64,PGgxPkhlbGxvIHN1bnNoaW5lISDimIDvuI88L2gxPgo=
While there are certain length limitations with Data URLs, this is a valid way to render the generated HTML in Hugo without relying on client-side JavaScript. Can we do better?
Turns out, there is a much easier way.
Meet the srcdoc attribute. It accepts an HTML document string as its value and uses that for building and rendering the iframe’s document — no need for Base64 or URL-encoding and all that crap. If you inspect the playground at the beginning of this article, you’ll find the following iframe:
<iframe
sandbox="allow-scripts"
loading="lazy"
referrerpolicy="no-referrer"
srcdoc="
<!DOCTYPE html>
<html>
<head>
<style>
body {
font-family: ui-sans-serif, sans-serif;
}
h1 { color: orangered; }
</style>
</head>
<body><h1>Hello world!</h1></body>
<script>console.log("Hello world!");</script>
</html>">
</iframe>
Quite simple, isn’t it? Best of all, I could do this with Hugo’s templating system and there’s zero JavaScript involved:
<iframe
sandbox="allow-scripts"
loading="lazy"
referrerpolicy="no-referrer"
srcdoc="{{- $srcDoc -}}">
</iframe>
Yes, I know I could probably also write this out as a separate document (resource) and link it but this is more fun and one less file.
If you ever decide to do something like this, do take care to escape the HTML string properly in the templating syntax/framework of your choice. In Hugo’s case, this is taken care of automatically in various HTML contexts.
An aside: this is not my first encounter with srcdoc. At my former company, Flock (think Slack), the messenger I worked on supported micro-frontend apps loaded via iframes and we allowed third-party apps via our app store. If I remember correctly, we explicitly supported providing us with the raw HTML document that represented the app instead of a URL. The messenger client would later fetch this HTML string and associated metadata of the app and inject it into an iframe on the sidebar using, you guessed it, the srcdoc attribute. I thought that was very code-smelly back then but the younger me could’ve never predicted the same attribute being used to implement something cool in his future blog. 🙃