https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public

---
name: wiki-readme-html
description: >-
  How to build a custom HTML readme (readme.html) for an Adom Wiki page — the
  fully designed, unsanitized alternative to README.md. Covers when to choose
  html over markdown, the shadowing rule (readme.html makes README.md invisible
  on the page), the sandboxed-iframe render pipeline and its exact limits
  (scripts run, but no same-origin, no cookies, no wiki API, external links and
  popups need care), self-containment (inline CSS/JS, base64 fonts/images,
  /blob/ asset URLs), the six readme variant slots (bare/public/private ×
  html/md), dark-theme styling so the page doesn't flash white, and the
  curl + pup verification loop. Read this BEFORE writing a readme.html and when
  one renders blank, unstyled, clipped, or won't update. Trigger words: html
  readme, readme.html, custom readme, custom html readme, designed readme,
  readme with tabs, readme with accordion, readme iframe, readme sandbox,
  readme shadowed, README_SHADOWED, readme.html not rendering, readme not
  updating, fully custom page layout, custom page body, unsanitized readme.
user-invocable: true
---

Parent skill: **adom-wiki-skillpack** · Sibling: **wiki-readme** (markdown mode +
the content rules that apply to BOTH modes)

# Building a custom HTML readme (readme.html)

Verified end to end 2026-07-15 with a live probe page (publish → API variants →
rendered iframe → styles applied → `<script>` ran).

## When to use html vs markdown

| Situation | Mode |
|---|---|
| Prose + images + tables sells the page fine | `README.md` (cheaper to write and maintain; see **wiki-readme**) |
| Tabs, accordions, toolbars, lightboxes, custom typography, interactive JS | `readme.html` |
| A component CAD hub with an Open-in toolbar + provenance lightbox | `readme.html` (see **wiki-component**) |

Markdown is still the right default. An HTML readme is a designed artifact: it
costs real effort to build well, and a half-styled HTML page reads worse than
clean markdown. Choose it when the layout IS the value.

## How to ship one

Put `readme.html` at the root of the publish tree and `adom-wiki pkg publish`.
The page registers it (API: `readme_variants_json.bareHtml = "readme.html"`)
and the Overview tab switches to HTML mode.

## The shadowing rule (the #1 gotcha)

`readme.html` **fully shadows README.md on the page**. The publish linter warns:
`README_SHADOWED: readme.html is what renders on the page, so edits to README.md
will not be visible.` Keep a README.md anyway — the Files tab, `repo clone`
readers, and git tooling still use it — but every page-visible edit goes in the
HTML file. If "my readme edit isn't showing up," check which file you edited.

## How it renders (and what the sandbox forbids)

Only HTML-mode pages get an iframe (markdown renders inline in the page). The
Overview embeds:

```
https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public
```

in `<iframe sandbox="allow-scripts allow-downloads">`. The endpoint serves your
file **byte-for-byte — no sanitizer**. Consequences:

- `<style>`, `style=`, and `<script>` all work. Scripts run inside the sandbox.
- **No `allow-same-origin`**: the iframe runs as an opaque origin. No cookies,
  no wiki session, no `fetch` to the wiki API, no localStorage. The readme
  cannot know who is viewing it or call authenticated endpoints.
- **No `allow-popups` / `allow-top-navigation`**: `target="_blank"` links and
  `window.open` are blocked by the sandbox. Plain same-frame links navigate the
  iframe itself, not the wiki page. Design navigation accordingly (prefer
  in-page JS interactions; verify any external link actually opens before
  relying on it).
- It is a full document of its own: include your own base styles; nothing
  cascades in from the wiki.

## Self-containment (assets)

Treat the file like an email template: everything inline.

- Inline all CSS and JS. Base64-inline fonts and small images.
- Repo files are reachable at absolute `/blob/<type>/<slug>/...` URLs for
  `<img>`/`<video>` — but note the known content-type bug (SVGs served as
  `application/octet-stream`, adom/wiki issue #38); PNG/JPG are safe.
- Never reference the hero image — the page header already renders it
  (**wiki-readme**'s #1 rule applies in both modes).

## Theme: the wiki is dark

The wiki chrome around your iframe is dark. A bare HTML file renders on a
default **white** body and will glare. Set your own background and text colors
explicitly (match the wiki's dark look or design deliberately), and follow the
Adom brand rules (tokens, brand fonts, monochrome icons, no emoji, no
em-dashes).

## Variants (public/private pages)

The page tracks six slots in `readme_variants_json`:
`bareHtml`/`bareMd`, `publicHtml`/`publicMd`, `privateHtml`/`privateMd`.
A plain `readme.html` registers as `bareHtml`. The html-vs-md choice composes
with the private-readme system for private-source/public-releases pages
(**wiki-visibility**) — the `?variant=` query selects which one renders.

## Verify loop (do all three)

1. **curl the endpoint** — confirm your exact bytes are live:
   `curl -s "https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public"`
2. **Open the page in pup** (cache-bust `?v=<ver>`) and screenshot — confirm the
   iframe shows your layout, styles applied, at a sane height with no clipping
   or double scrollbars. Iframe sizing is controlled by the page, not you —
   if your content clips, restructure toward a natural document flow and
   re-verify. (Sizing behavior is not yet fully characterized; report surprises
   on adom/wiki.)
3. **Check any JS actually ran** — bake a visible self-test into the page while
   iterating (an element whose text a script rewrites), remove it when done.

## Pitfalls recap

- Edited README.md, page unchanged → shadowing rule; edit readme.html.
- Renders but unstyled/white → you assumed wiki CSS; the iframe gets nothing.
- Buttons/links dead → sandbox blocks popups/top-nav; keep interactions in-frame.
- Fetch to the wiki API fails → no same-origin; the readme is display-only.
- SVG `<img>` broken → content-type bug (issue #38); use PNG or inline the SVG markup.
- Works locally, stale on the wiki → you pushed the repo but didn't `pkg publish`
  (or vice versa); the readme the page renders comes from the published layer.