|
| 1 | +# Embedding Unraid Docs |
| 2 | + |
| 3 | +Use the following guidance when loading the Unraid documentation inside an iframe-driven experience. Query parameters cover the most common configuration options, and an optional `postMessage` API is available for hosts that need dynamic coordination. |
| 4 | + |
| 5 | +## Required Query Parameters |
| 6 | + |
| 7 | +- `embed=1` — Opts the page into iframe-specific presentation tweaks (hides the global navbar, footer, etc.). Include this on every embedded URL. |
| 8 | + |
| 9 | +## Optional Query Parameters |
| 10 | + |
| 11 | +- `theme=<light|dark>` — Forces the initial Docs theme. The value is persisted for the iframe session so reloads stay consistent. |
| 12 | +- `entry=<path>` — Marks the logical entry point for the iframe session. Supply an absolute docs path (e.g. `/unraid-os/...`) or a full docs URL; the embedded UI shows a floating back icon that returns visitors to this path and hides itself while you remain on it. Defaults to the first loaded URL if omitted. |
| 13 | +- `sidebar=1` — Re-enables the documentation sidebar and table of contents, which are hidden by default in embedded mode. |
| 14 | + |
| 15 | +## Session Storage Keys |
| 16 | + |
| 17 | +The iframe experience uses `window.sessionStorage` to remember state while a browser tab stays open. Host applications normally do not need to interact with these keys, but they are listed here for completeness. |
| 18 | + |
| 19 | +| Key | Purpose | |
| 20 | +| --- | --- | |
| 21 | +| `unraidDocsIframe` | Tracks whether the current session originated inside an iframe. | |
| 22 | +| `unraidDocsTheme` | Stores the last used Docs theme so reloads stay consistent. | |
| 23 | +| `unraidDocsIframeEntry` | Holds the iframe entry path for the fallback back button. | |
| 24 | +| `unraidDocsIframeSidebar` | Marks whether the sidebar was explicitly enabled. | |
| 25 | + |
| 26 | +A host can clear these keys to reset the embedded state before opening a new iframe session. |
| 27 | + |
| 28 | +## Example URL Builders |
| 29 | + |
| 30 | +```js |
| 31 | +function buildDocsUrl(path, { theme, entry, sidebar } = {}) { |
| 32 | + const url = new URL(path, "https://docs.unraid.net"); |
| 33 | + url.searchParams.set("embed", "1"); |
| 34 | + |
| 35 | + if (theme === "light" || theme === "dark") { |
| 36 | + url.searchParams.set("theme", theme); |
| 37 | + } |
| 38 | + |
| 39 | + if (entry) { |
| 40 | + url.searchParams.set("entry", entry); |
| 41 | + } |
| 42 | + |
| 43 | + if (sidebar) { |
| 44 | + url.searchParams.set("sidebar", "1"); |
| 45 | + } |
| 46 | + |
| 47 | + return url.toString(); |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +## Recommended Host Flow |
| 52 | + |
| 53 | +1. Decide which route should serve as the iframe entry point and supply it via `entry` when loading the iframe. |
| 54 | +2. Pass the current host theme if you want the Docs theme to match immediately. |
| 55 | +3. Toggle `sidebar=1` only when the host layout can accommodate the wider viewport required for the sidebar. |
| 56 | +4. When tearing down an iframe session, optionally clear the session-storage keys to remove residual state before launching a new session in the same tab. |
| 57 | + |
| 58 | +## Messaging API |
| 59 | + |
| 60 | +The embedded docs surface a lightweight `postMessage` API that reports readiness, navigation, and theme changes using structured message types. All messages share the shape `{ source: "unraid-docs", type: string, ...payload }` so hosts can quickly filter for docs-specific traffic. |
| 61 | + |
| 62 | +### Messages emitted from the iframe |
| 63 | + |
| 64 | +| Type | Payload | Purpose | |
| 65 | +| --- | --- | --- | |
| 66 | +| `unraid-docs:ready` | `{ theme: "light" \| "dark" }` | Fired once the iframe has applied its starting theme. | |
| 67 | +| `unraid-docs:theme-change` | `{ theme: "light" \| "dark" }` | Fired whenever the iframe theme changes (including the initial emission). | |
| 68 | +| `unraid-docs:navigation` | `{ pathname, search, hash, url }` | Fired whenever in-iframe navigation occurs. | |
| 69 | + |
| 70 | +### Commands accepted by the iframe |
| 71 | + |
| 72 | +| Type | Payload | Purpose | |
| 73 | +| --- | --- | --- | |
| 74 | +| `unraid-docs:set-theme` | `{ theme: "light" \| "dark" }` | Requests a theme change without requiring a reload. | |
| 75 | + |
| 76 | +Example host handler: |
| 77 | + |
| 78 | +```js |
| 79 | +window.addEventListener('message', (event) => { |
| 80 | + const data = event.data; |
| 81 | + if (!data || data.source !== 'unraid-docs') { |
| 82 | + return; |
| 83 | + } |
| 84 | + |
| 85 | + if (data.type === 'unraid-docs:theme-change') { |
| 86 | + console.log('Docs theme changed to', data.theme); |
| 87 | + } |
| 88 | +}); |
| 89 | + |
| 90 | +function setIframeTheme(frame, theme) { |
| 91 | + if (!frame.contentWindow) { |
| 92 | + return; |
| 93 | + } |
| 94 | + |
| 95 | + frame.contentWindow.postMessage({ |
| 96 | + source: 'unraid-docs', |
| 97 | + type: 'unraid-docs:set-theme', |
| 98 | + theme, |
| 99 | + }, '*'); |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +Refer to `iframe-test.html` for a working example that exercises both outgoing and incoming messages. |
| 104 | + |
| 105 | +### Legacy compatibility |
| 106 | + |
| 107 | +For backwards compatibility the iframe still listens for `{ type: "theme-update", theme }` and continues to emit the historical `theme-ready` and `theme-changed` messages alongside the new message types. Hosts should migrate to the structured `unraid-docs:*` contract because the legacy events will be removed in a future release. The example test page also demonstrates how to broadcast both message formats during the transition period. |
0 commit comments