To embed HTML in Notion, type /html, choose HTML · Embeds and upload your .html file. Notion added this HTML block in Notion 3.6, released on 1 July 2026, and it runs the file inside your page.
Notion's developer reference says the block "renders the file's contents interactively in a sandboxed iframe", and that it is "the same block the app creates with the /html command".
This guide covers the five steps, what we saw when we tested the block, and the cases where giving the page its own link suits the reader better.
How to embed HTML in Notion with /html: 5 steps
- Save the HTML as a .html file. The block takes a file, not pasted code. If the code is in an AI chat, copy it into a text editor and save it with the
.htmlextension. - Type
/htmlin Notion. On an empty line, type/htmland choose HTML · Embeds from the menu. - Upload the file. The block offers two ways in: Upload HTML file, or Create with AI from a description. Drag your file onto the block or choose it from your computer.
- Check that it runs. The page appears inside the block with its styles applied. Scripts run and buttons respond.
- Replace the file to update it. There is no code editor in the block. Save a new version of the file, open the block menu and choose Replace.
A self-contained file, with its styles and scripts written inside it rather than in separate files, is the simplest thing to upload.
What we saw when we tested the block
We tested the block on 27 September 2026 in the Notion web app with a new account. The test file had styles, a script and a button with a click counter.
| What we checked | Result |
|---|---|
| Styles in the file | Applied |
| Scripts | Ran |
| A button with a click counter | Worked |
| A request to an outside address (fetch) | Blocked |
| Pasting the HTML code as text into the page | Shown as code text, not rendered |
| Editing the code inside the block | No menu option; replace the file or use AI |
| Page published to the web, visitor not logged in | Block ran (checked in a desktop browser) |
Two points follow from that table. A page that pulls live data from another site will not get it inside the block, so build the data into the file. And the page is shown inside the document, under the page title, in a block frame.
For a page that belongs next to your notes, that is the right place for it. A chart sitting above the meeting notes it summarises is easier to read there than behind a link.
When a separate link works better
The HTML block answers one question well: how do I put this page into my Notion doc? Sending a page to someone is a different job, and for that a page with its own address can fit better.
In NOS you paste the HTML into a document, either as code text or by importing the .html file, and it renders as written with its scripts running. Create share link then gives the page its own full-screen address.
| Inside Notion (HTML block) | Its own NOS link | |
|---|---|---|
| What you start from | A saved .html file, or a Notion AI prompt | The code as text, or the .html file |
| Where the reader sees it | Inside the Notion page, under the title, in a block frame | Full screen, as a page on its own |
| Changing the code | Replace the file from the block menu | Edit the code; the link stays the same |
| Who can open it | People who can see the Notion page, or visitors if you publish it | Anyone with the link, no account needed |
| Requests to outside addresses | Blocked | Blocked |
A separate link is the better fit in these cases:
- You have the code as text, not a file. An AI chat hands you code. Pasting it into a NOS document skips the step of saving a file.
- You want it full screen. A dashboard or a slide deck uses the whole browser window instead of sitting inside a document.
- You will keep changing it. Edit the code and the address people already have keeps working, showing the new version.
- The reader has no reason to open Notion. A client or a friend gets one link that opens as a page, with no account.
People who open a NOS share link can view the page but cannot edit it.
Turning HTML into a link walks through it in one paste. Using both is also reasonable: the HTML block for pages that live in your wiki, a link for pages that go out to other people.
The older route: embed a page by its address
Before the HTML block, the way to show a web page in Notion was the embed block with an address, and it still exists. Type /embed, paste the address and choose Embed link.
It only works for pages that allow being shown inside another site. Many pages refuse that, and the embed then stays blank or shows an error. NOS share links are among them: they open as a page of their own, not inside an embed.
So the embed block suits a page that already lives at a public address and allows framing. For your own HTML file, the HTML block above is the direct route. The iframe guide explains how a page refuses to be framed.
Before you embed: a quick check
- Is it one file? Styles and scripts inside the file, not in separate files next to it.
- Does it fetch data from another site? Those requests are blocked in the HTML block and on a NOS share page alike. Put the data in the file.
- Where will it be read? Next to your notes, use the HTML block. Sent to someone outside Notion, use a link.
- Will you keep editing it? With the HTML block you replace the file. With a share link you edit the code and the address stays.