How to Fix Iframe Not Showing or Not Rendering in Hugo Using the RawHTML Shortcode

When using Hugo, many users encounter issues when inserting an <iframe> into article content, the iframe does not appear or is not rendered at all on the website page.

This usually happens when we add HTML code directly inside a Markdown (.md) file. By default, Hugo (especially with the Goldmark configuration) restricts or disables raw HTML for security reasons. As a result, elements like <iframe> are ignored or not processed.

This issue is quite common, especially when trying to embed content from YouTube, Google Maps, or other third-party widgets. Fortunately, there is a simple and clean solution without needing to modify Hugo’s global configuration.

In this article, we will discuss how to fix iframes not showing in Hugo using a custom shortcode.

Why Is the Iframe Not Showing?

#

By default, Hugo uses a Markdown renderer called Goldmark. If the unsafe setting is not enabled, raw HTML inside Markdown will be blocked. Since <iframe> is considered raw HTML, it will not be rendered.

Instead of modifying the global configuration like this:

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

we can use a safer and more controlled approach: Shortcode.

Solution: Using the rawhtml Shortcode

#

1. Create the Shortcode File

#

Create the following file inside the folder:

layouts/shortcodes/rawhtml.html

Add the following code:

<!-- raw html -->
{{.Inner}}

This shortcode functions to process its inner content as raw HTML.

2. How to Use the Shortcode

#

Inside your article Markdown file, wrap the iframe code with the following shortcode:

{{< rawhtml >}}
<iframe 
    width="560" 
    height="315" 
    src="https://www.youtube.com/embed/VIDEO_ID" 
    frameborder="0" 
    allowfullscreen>
</iframe>
{{< /rawhtml >}}

With this method, Hugo will properly render the iframe content without needing to enable unsafe = true.

Why Is Using a Shortcode Better?

#

Some advantages of this approach:

• ✅ No need to modify global configuration
• ✅ Safer because only specific HTML is processed
• ✅ Cleaner and reusable
• ✅ Suitable for various embeds (YouTube, Google Maps, etc.)

This method is highly recommended, especially if your website has multiple contributors or if you want to keep content security under control.

FAQ

#

1. Why is the iframe still not showing after using the shortcode?

#

Make sure:

• The rawhtml.html file is located inside the layouts/shortcodes/ folder
• The shortcode is written correctly (all lowercase)
• There are no syntax errors in the iframe

2. Is this method safe?

#

Yes, it is safer compared to enabling unsafe = true globally. With a shortcode, only specific sections are allowed to process raw HTML.

3. Can it be used for HTML other than iframe?

#

Yes. This shortcode can also be used for:

• Embed scripts
• Third-party widgets
• Custom HTML layouts
• External forms

However, use it wisely.

4. Is there another way besides using a shortcode?

#

Yes, by enabling:

unsafe = true

However, this method allows all raw HTML throughout the entire content, so it is less recommended unless absolutely necessary.

Conclusion

#

The issue of iframes not rendering in Hugo generally occurs due to raw HTML restrictions by Goldmark. The safest and most flexible solution is to create the rawhtml.html shortcode and wrap the iframe inside it.

With this approach, you do not need to modify the global configuration and can safely embed various external content.

If this article helped, feel free to give a vote or leave feedback in the Disqus comment section. Your support means a lot 🙌