Embed

Embed one section in another site's page through a declarative shadow root. Its styles stay inside, the host's stay out, and no script runs.

What it rendersCopy Anchor Link

The section the steps below embed, a command-row, rendered alone as this site draws every preview:

{
  "kind": "band",
  "shell": {
    "inset": "contained",
    "density": "compact"
  },
  "block": {
    "type": "command-row",
    "command": "npm i @example/harbor-tides",
    "note": "Node.js 22 or later"
  }
}

{
  "title": "command-row",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "command-row"
    },
    "command": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 48
    }
  },
  "required": [
    "type",
    "command"
  ],
  "additionalProperties": false
}

PrerequisitesCopy Anchor Link

• The quickstart runs in your project, with @mdxui/themes installed as on Packages and versions.
• A host page that loads the Theme's typefaces, since a shadow root inherits fonts from its host.

StepsCopy Anchor Link

1. Render the section under a Theme:

   Copy Text

   const block = BlockSchema.parse({ type: 'command-row', command: 'npm i @example/harbor-tides', note: 'Node.js 22 or later' });
   const { theme, css } = THEMES.quaypoint;
   const html = renderBlock(block, context(theme, 'paper', theme.icons));

2. Wrap it in a shadow root with the Theme's tokens and the Section type CSS. The tokens move from :root to :host:

   Copy Text

   // A declarative shadow root: the section's styles stay inside it, and the host's stay out. No script.
   const embed = `<div class="mdxui-embed">
     <template shadowrootmode="open">
       <style>${css().replaceAll(':root', ':host')}${baseCss}${primitivesCss}${blocksCss}</style>
       ${html}
     </template>
   </div>`;

3. Write embed into the host page's HTML, where the browser attaches the shadow root as it parses.

ResultCopy Anchor Link

embed.html: a host paragraph, then the command-row in quaypoint, styled by its own sheet and untouched by the host's.

A React page that is prerendered, as a Fumadocs page is, writes the same string into its HTML. A page rendered in the browser attaches a shadow root with attachShadow and sets its innerHTML instead. This site's previews take a third path: each is a frame, an iframe of one prerendered section.

RelatedCopy Anchor Link