---
name: wiki-readme
description: >-
  How to make a great Adom Wiki page presentation — the README is the page. Covers
  the choice between a plain README.md and a fully custom readme.html, the
  mandatory sections every page needs, embedding live demos / videos / iframes,
  and referencing inline images from the repo. Read this when writing or fixing
  the Overview tab of a wiki page, and BEFORE adding any image to a README —
  NEVER embed the page hero in the README body (the page header already shows it,
  so embedding it makes the human see the same image twice). Trigger words: how to
  make a readme, wiki readme, readme.html, custom readme, write a readme for the
  wiki, wiki page overview, embed iframe wiki, embed demo, inline images readme,
  wiki page presentation, mandatory readme sections, readme renders blank, hero in
  readme, embed hero, hero image in readme, hero in the body, hero shows twice,
  duplicate hero, repeated hero, don't repeat the hero, readme hero image, add
  image to readme, readme screenshots.
---

Parent skill: **adom-wiki-skillpack**

# How to make a README (the presentation layer)

On the Adom Wiki the **README is the page** — the Overview tab is the first thing
a human sees, and it's what sells the page in search and on cards. There are TWO
presentation modes:

1. **`README.md`** (the default) — rendered through `marked` **then sanitized**,
   so what you can build is limited (below).
2. **`readme.html`** (custom HTML mode, LIVE — verified end to end 2026-07-15) —
   your HTML renders as the page body in a **sandboxed iframe**, completely
   unsanitized: inline `<style>` AND `<script>` both work. The nuances (sandbox
   limits, self-containment, theming, variants, verify loop) have their own
   skill: **wiki-readme-html**. The summary below is just the map.

## Custom HTML mode: readme.html (full designed layouts)

Ship a `readme.html` in the publish tree and `pkg publish`. That's it.

- **It shadows README.md entirely.** The publish linter says so:
  `README_SHADOWED: readme.html is what renders on the page, so edits to
  README.md will not be visible.` Keep a README.md for the Files tab and git
  readers, but know the page ignores it.
- **How it renders:** the Overview tab embeds
  `https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public` in an
  iframe with `sandbox="allow-scripts allow-downloads"` (no `allow-same-origin`).
  The endpoint serves your HTML byte-for-byte — no sanitizer. Styles apply,
  scripts run (verified live: styled tabs rendered, a `<script>` mutated the DOM).
- **Sandbox limits:** no same-origin access (no cookies, no wiki API calls from
  the readme), no top-navigation. Self-contain everything: inline CSS/JS,
  base64-inline fonts and images or use absolute `/blob/...` URLs.
- **Variants:** the page tracks six readme slots in `readme_variants_json` —
  `bareHtml`/`bareMd`, `publicHtml`/`publicMd`, `privateHtml`/`privateMd` — so
  the html-vs-md choice composes with the public/private readme split
  (see **wiki-visibility**). A plain `readme.html` registers as `bareHtml`.
- Tabs, accordions, toolbars, provenance lightboxes — all buildable here. This
  is the mode the old "standalone prototype in the container" workaround was
  waiting for; prototype straight in `readme.html` now.

## Markdown mode: what HTML survives (the sanitizer reality)

The rendered README.md is run through `sanitize-html` with a **strict allowlist**.
It **strips `<style>`, `<script>`, `<details>`/`<summary>`, `<iframe>`, and even
`style=` attributes.** Surviving tags: `h1-6, p, a, ul/ol/li, blockquote, pre,
code, em, strong, del, ins, sub, sup, kbd, hr, br, img, table/thead/tbody/tr/th/td,
span, div, input` (task lists), with `class` on a few and `href/src/alt/width/
height/align`. **Consequence: you cannot build a tabbed / accordion / toolbar
"custom HTML layout" in README.md** — inline styles vanish, `<details>` collapse,
scripts never run. (Confirmed live: a hand-styled toolbar rendered as plain links.)

So README.md is for **prose + images + tables**. For anything richer:
- **Switch to `readme.html`** (above) for a fully designed layout.
- **Component pages** get rich interactive UI from the wiki's **native rendering**
  (symbol/footprint/3D viewers, downloads grid) — see **wiki-component**, not the README.

There is also a **private readme** for pages whose git source is private but whose
releases are public — see **wiki-visibility**.

## Provenance: cite your sources (engineers don't trust AI yet)

Every non-obvious claim on a page should name where it came from: a datasheet page,
a distributor + date, a manufacturer URL, the tool + input hash that produced an
artifact. For datasheet-derived data, show the **page number and a cropped image of
that page**. This is mandatory on component/chip pages (full pattern + tooling in
**wiki-component**), and good practice everywhere — provenance is what turns "the AI
said so" into "here's the page it's on."

## ⛔ THE #1 README RULE: NEVER embed the hero image in the README body

**The wiki renders the hero at the top of the page automatically** (from
`page.json` → `hero.path`). If you ALSO drop the hero image into the README body,
the human sees the **same image twice**, back to back — which is redundant,
annoying, and reads as careless. **Do not `![...](.../screenshots/hero.png)` in the
README. Ever.** This is the single most common README mistake on the wiki, so it
goes first.

- The hero lives in **`page.json` only** (see **wiki-hero**). The README never
  references it.
- Inline images in the README must be **OTHER** images — different screenshots,
  states, diagrams — never the hero, and never a near-duplicate of it.
- Before publishing, grep the README: if it points at `hero.png` (or whatever the
  `page.json` hero path is), delete that line.

## The README is for humans, and humans need images

**Never publish a text-only README.** Any page with a UI needs inline
screenshots and an embedded live demo. But the **hero** is supplied via
`page.json` and shown at the top of the page for you — the README's images are
the *additional* ones (different views/states/diagrams). A skill `description` is
for the AI — the README is for the person deciding whether to install.

## Mandatory sections (in this order)

1. **Title + one-line description** — the title is a **human, descriptive name,
   NEVER the slug echo** (`Wiki Hero Image Skill`, not `adom-wiki-hero-image`).
   Set it in `page.json` AND `package.json` (publish resets a missing manifest
   title to the slug). → **wiki-repo-styles**.
2. **(The page header already shows the hero — do NOT embed it here.)** Go
   straight from the description into content. Set the hero in `page.json`, not
   the README (see **wiki-hero**).
3. **Live demo** (if there's any UI) — an `<iframe>` of a self-contained
   `demo/index.html` with baked-in sample data (no server dependency).
4. **Install** — `adompkg install <slug>`
5. **Quick start** — 3–5 lines showing the most common workflow
6. **Feature images** — for an app, show **exactly 3 inline images of the major
   elements of the app**, each under its own `##` heading and each **described in
   detail**: a full paragraph on *what's in the shot and why it matters*, not a
   one-line caption. Make the three DIFFERENT elements (e.g. the control panel,
   the rendered output, the signature feature) — and never the hero. A close-up
   crop of a region is a fine "different" image; an identical copy of the hero is
   not. (Pattern proven on adom-symbol / adom-footprint / adom-lbr, 2026-06-21.)
7. **Dependencies** — a table: Dependency / Required? / Why (explain the *why*)
8. **Features** — bullet list
9. **Talk to the AI** — paste-ready prompts grouped by action, using the exact
   trigger words so routing works (this teaches humans the vocabulary)
10. **Skills** — table of the main skill + sub-skills with a purpose column
11. **CLI reference** — command table (if there's a CLI)

## Open-source pages need a "check it out, vibe-code it, send it back" section

If the page's source is public (open source), the README MUST teach the
contribution loop — otherwise "open source" is a hollow claim. The proven section
(used across the Adom EDA apps, 2026-06-21) is a `## Open source` heading with a
short intro ("the complete source is in this page's **Files** tab") plus four
numbered steps:

1. **Build it** — the one-command build (`cargo build --release`, etc.).
2. **Point your install at your checkout** — `adompkg link <owner>/<slug> ./<dir>`
   so the installed command runs the local copy.
3. **Vibe-code a change** — open the folder in Claude Code and describe the change;
   name a couple of concrete, small extension points so it feels approachable.
4. **Send it back** — open a **pull request** on the page (the wiki merges per-repo
   PRs) or start a discussion thread.

For this to be TRUE, you must actually push the source (`src/` + build manifest)
into the page repo so the Files tab really shows it — don't write the section
against source that isn't there. Don't invent a `git clone` URL you haven't
verified; lean on the **Files** tab, `adompkg link`, and PRs, which exist.

## Embeds

Inline image from the repo (blob endpoint) — point at a NON-hero screenshot
(`feature-1.png`, a diagram, a different state), never `hero.png`:

```markdown
![Results view](/blob/<type>/<slug>/screenshots/feature-1.png)
```

Self-contained demo (bake sample data into the HTML, no fetch/WebSocket):

```html
<iframe src="/blob/app/<slug>/demo/index.html" width="100%" height="500"
  frameborder="0" style="border-radius:8px;border:1px solid #333;"></iframe>
```

Video — local file from the repo (the blob endpoint supports Range, so seeking
works), or YouTube via `youtube-nocookie.com`, or Vimeo:

```html
<video width="100%" controls poster="/blob/app/<slug>/screenshots/hero.png">
  <source src="/blob/app/<slug>/demo/walkthrough.webm" type="video/webm"></video>
```

## Known rendering pitfalls

- Inline images can 404 on `<img>` HEAD preflight (a wiki bug) even though the
  tag is correct — always verify visually in pup.
- After `adompkg publish`, the page title/brief reset to the package values;
  re-push a complete `page.json` to restore them (see **wiki-publish-safely**).