Skip to content

embedding.md

Latest commit

 

History

History
118 lines (84 loc) · 5.64 KB

embedding.md

File metadata and controls

118 lines (84 loc) · 5.64 KB

Embedding Unraid Docs

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.

Required Query Parameters

  • embed=1 — Opts the page into iframe-specific presentation tweaks (hides the global navbar, footer, etc.). Include this on every embedded URL.

Optional Query Parameters

  • theme=<light|dark> — Forces the initial Docs theme. The value is persisted for the iframe session so reloads stay consistent.
  • 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.

Session Storage Keys

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.

Key Purpose
unraidDocsIframe Tracks whether the current session originated inside an iframe.
unraidDocsTheme Stores the last used Docs theme so reloads stay consistent.
unraidDocsIframeEntry Holds the iframe entry path for the fallback back button.

A host can clear these keys to reset the embedded state before opening a new iframe session.

Example URL Builders

function prefixLocale(path, locale) {
  const cleanLocale = (locale || "").toLowerCase();
  if (!cleanLocale || cleanLocale === "en") {
    return path;
  }

  const trimmed = path.replace(/^\/+/, "");
  const segments = trimmed.split("/").filter(Boolean);

  if (segments[0]?.toLowerCase() === cleanLocale) {
    return `/${segments.join("/")}`;
  }

  return `/${cleanLocale}/${segments.join("/")}`;
}

function buildDocsUrl(path, { theme, entry, locale } = {}) {
  const localizedPath = prefixLocale(path, locale);
  const url = new URL(localizedPath, "https://docs.unraid.net");
  url.searchParams.set("embed", "1");

  if (theme === "light" || theme === "dark") {
    url.searchParams.set("theme", theme);
  }

  if (entry) {
    url.searchParams.set("entry", entry);
  }

  return url.toString();
}

Recommended Host Flow

  1. Decide which route should serve as the iframe entry point and supply it via entry when loading the iframe.
  2. Pass the current host theme if you want the Docs theme to match immediately.
  3. Prefix the docs path with the desired locale segment (for example /es/...) if you want to start in a translated version. The iframe experience reads the language from the pathname, not from a query parameter.
  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.

Messaging API

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.

Messages emitted from the iframe

Type Payload Purpose
unraid-docs:ready { theme: "light" | "dark" } Fired once the iframe has applied its starting theme.
unraid-docs:theme-change { theme: "light" | "dark" } Fired whenever the iframe theme changes (including the initial emission).
unraid-docs:navigation { pathname, search, hash, url } Fired whenever in-iframe navigation occurs.

Commands accepted by the iframe

Type Payload Purpose
unraid-docs:set-theme { theme: "light" | "dark" } Requests a theme change without requiring a reload.

Example host handler:

window.addEventListener('message', (event) => {
  const data = event.data;
  if (!data || data.source !== 'unraid-docs') {
    return;
  }

  if (data.type === 'unraid-docs:theme-change') {
    console.log('Docs theme changed to', data.theme);
  }
});

function setIframeTheme(frame, theme) {
  if (!frame.contentWindow) {
    return;
  }

  frame.contentWindow.postMessage({
    source: 'unraid-docs',
    type: 'unraid-docs:set-theme',
    theme,
  }, '*');
}

Refer to iframe-test.html for a working example that exercises both outgoing and incoming messages. The local docs dev server uses http://localhost:3001 by default, and the example page assumes that port.

Legacy compatibility

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.