How to Embed a Widget in GitBook
GitBook supports URL embeds natively — paste a URL and GitBook renders it as an interactive inline embed. Your Embeddy widget URL works seamlessly with GitBook's embed block, making it easy to add live widgets to your documentation without any code or plugins.
On this page
Prerequisites
Before embedding, make sure you have the following ready:
- An Embeddy widget: Create one for free at embeddy.ai/dashboard. Your widget must be published (not in draft mode) so it is publicly accessible.
- Your Embed Link: In the Embeddy dashboard, open your widget and copy the Embed Link — the direct URL that looks like
https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID. - A GitBook space: Any GitBook plan works — Community (free), Plus, Pro, or Enterprise. Embeds are supported on all plans. You need edit access to the space.
Where is my Embed Link? In the Embeddy dashboard, select your widget, click the Share / Embed panel, and look for the Embed Link option. It is the direct URL — not the <iframe> snippet.
Method 1: Embed URL Block
Recommended — most explicit method
GitBook's Embed a URL block is the dedicated content block for displaying external web content inline. It uses the Iframely/oEmbed protocols to resolve URLs and render them as interactive embeds.
- 1
Open your GitBook page in the editor
Navigate to your GitBook space and click into the page you want to edit. If you are using GitBook's change request workflow, start or continue a change request first.
- 2
Insert an embed block
Click the + button on an empty line, or type
/embed. Select Embed a URL from the block menu. - 3
Paste your Embeddy widget URL
An input field appears. Paste your Embed Link:
https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID
- 4
Press Enter
GitBook will resolve the URL and render the embed block. Depending on how GitBook resolves the URL, it may display a rich embed or an iframe. Either way, your Embeddy widget will be interactive and functional.
- 5
Publish or merge your changes
If you are in a change request, submit and merge it. If editing directly, save the page. The widget will appear on the published documentation site.
Tip: GitBook's editor shows a live preview of the embed. Use this to verify the widget loads correctly before publishing your changes.
Method 2: Paste URL Directly
Quick alternative — GitBook auto-detects the URL
GitBook can automatically detect pasted URLs and convert them to embed blocks. Simply paste the URL on an empty line and GitBook will offer to create an embed.
- 1
Click on an empty line in the editor
Place your cursor on a blank line where you want the widget to appear.
- 2
Paste the widget URL
Paste your Embeddy Embed Link. GitBook may display a prompt asking how to display the URL:
- →Embed — renders the content as an inline embed (choose this)
- →Link — keeps it as a plain clickable URL
- 3
Select "Embed"
Choose the embed option. GitBook will create an embed block and render your widget inline.
Note: If GitBook does not auto-detect the URL for embedding, use Method 1 to explicitly create an embed block. The /embed command always works regardless of URL detection.
Resizing the Widget
GitBook provides visual controls to resize embed blocks after insertion.
Adjust Size
Click the embed block to select it. Resize handles appear on the edges. Drag them to adjust the width and height. GitBook embeds default to a reasonable size, but you can customize them to fit your page layout.
Block Options
Click the block options menu (three dots) on the embed block to access additional settings. You may be able to set an explicit size or switch between embed display modes depending on your GitBook version.
Documentation layout: For the best visual impact, place the embed block on its own line with no other content beside it. This gives it the full content width and makes the widget easier to interact with.
Limitations
GitBook embeds are straightforward but have a few platform-level constraints:
URL resolution
GitBook uses oEmbed and Iframely to resolve URLs. If a URL is not recognized by these services, GitBook may fall back to displaying a simple link or a generic iframe. Embeddy URLs render correctly, but you may not see rich metadata (title, thumbnail) in the editor.
No raw HTML support
GitBook does not support pasting raw HTML or iframe code. You must use the URL-based embed method. Copy the Embed Link (the URL) from the Embeddy dashboard, not the iframe snippet.
Change request workflow
If your GitBook space uses change requests, embeds added in a change request will only be visible on the published site after the change request is merged. You can preview the embed in the change request view.
PDF export
Embeds are interactive web content and will not appear in GitBook's PDF export. When exporting to PDF, the embed block will be replaced with a link to the widget URL.
Troubleshooting
Embed shows as a plain link
If your URL appears as a link rather than an embed, try these fixes:
- Use the /embed command. Delete the link and use Method 1 to explicitly create an embed block.
- Check the URL is valid. Open the Embed Link in a new browser tab to confirm it loads correctly.
- Make sure the widget is published. Draft widgets are not accessible at the embed URL.
Embed block shows a blank frame
A blank frame means the URL loaded but the content could not render. Ensure the widget visibility is set to Public in the Embeddy dashboard. Widgets that require login will not load in GitBook's sandboxed iframe.
Widget works in editor but not on published site
If you are using change requests, make sure the change request has been merged. If editing directly, verify the page has been saved and published. Try hard-refreshing the published page to clear the browser cache.
Widget is cut off or too small
Click the embed block and drag the resize handles to increase dimensions. Embeddy widgets are responsive and will adapt to the available space. For the best result, give the embed block the full content width.
Still stuck? Reach out on Discord or contact support. Share your widget's Embed Link and a screenshot of your GitBook page and we will help you debug it.
FAQ
Does this work with GitBook's free plan?
Yes. Embed blocks are available on all GitBook plans including the free Community plan. There are no plan restrictions on embedding URLs.
Can I use the Embeddy iframe code instead of the URL?
No. GitBook does not support raw HTML or iframe code. Use the Embed Link (the direct URL) from your Embeddy dashboard. GitBook's embed block accepts URLs only.
Will the widget update automatically if I change it in Embeddy?
Yes. GitBook embeds load the live URL each time the page is viewed. Any changes you make to your widget in the Embeddy dashboard are reflected on your published GitBook site immediately — no need to re-embed or update the URL.
Will the embed be visible to my documentation readers?
Yes. Anyone who can view your published GitBook page can see and interact with the embedded widget. The widget loads from Embeddy's servers and does not require readers to have an Embeddy account.
Ready to embed your widget?
Head to your Embeddy dashboard to create or find your widget, copy the Embed Link, and drop it into any GitBook page in seconds.