---
name: wiki-subreadme
user-invocable: true
description: >-
  What a "sub-readme" is on the Adom Wiki and how to make one. A sub-readme is a
  README.md placed inside a SUBFOLDER of a page's repo, which the wiki renders as
  its own sub-page when you browse into that folder (the way GitHub renders a
  folder's README). Use it to attach a substantial document to a page (an event
  plan, a meeting recap, a runbook) without cluttering the main README and without
  minting a whole new wiki page. Read this when someone says "sub-readme",
  "sub readme", "subreadme", "a README in a subfolder", "add a sub-page to this
  wiki page", "folder README", "nested doc on a wiki page", or "share this doc on
  our page but not on the main overview".
---

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

# Sub-readmes

A **sub-readme** is a `README.md` inside a **subfolder** of a page's git repo. The
wiki renders that folder's `README.md` as its own sub-page when a reader browses
into the folder from the Files tab, exactly like GitHub renders a folder's README.

It is the right tool when you want a real, rendered document living **on an
existing page** (an event plan, a meeting recap, a runbook, a spec), but:

- it does not belong in the **main README** (that is the page's overview and should
  stay focused), and
- it does not deserve a **separate wiki page** (that is bloat, see the parent
  skill's wiki-bloat rule).

So: not the main README, not a new page, not a family child page. A folder with a
`README.md` on the page you already have.

## What it is NOT

- **NOT the main `README.md`** at the repo root (that is the Overview tab, see
  `wiki-readme`).
- **NOT a family child page** (a separately published page with its own slug,
  title, hero, and discovery, see `wiki-family`). A sub-readme has no slug and does
  not show up in search or on cards. It lives entirely inside its parent page.
- **NOT a loose, oddly-named `.md` at the repo root** that you link by hand. That
  is the anti-pattern this skill exists to prevent. The folder + `README.md`
  convention is what makes it render as a browsable sub-page.

## How to make one

1. Pick a clear folder name, kebab-case, that reads as a path segment:
   `september-dc-event/`, `virtual-meeting-04aug2026/`, `runbooks/oncall/`.
2. Put the doc at `<folder>/README.md`.
3. Put its assets **inside the same folder**, but reference them with
   **ABSOLUTE blob URLs**, not relative paths. This is the trap: a sub-readme
   renders via the **Files tab** at `/<owner>/<slug>/files/<folder>`, and in that
   render a relative `img/x.jpg` resolves against the Files-tab route (a page
   URL), NOT the file blob, so **every relative image and asset link 404s**.
   (Relative paths only work in the ROOT `README.md` on the Overview tab, whose
   renderer rewrites them; the Files-tab sub-page renderer does not.)

   Use the blob endpoint, `/blob/<type>/<slug>/<repo-path>` (type is the page's
   type: `app`, `skill`, `component`, ...; no owner in a blob path):

   ```
   september-dc-event/
     README.md   # ![shot](https://wiki.adom.inc/blob/app/<slug>/september-dc-event/img/workcell.jpg)
     img/workcell.jpg
   virtual-meeting-04aug2026/
     README.md   # ![Slide 1](https://wiki.adom.inc/blob/app/<slug>/virtual-meeting-04aug2026/slides/slide-01.jpg)
     slides/slide-01.jpg   # PDFs, videos, any asset: same absolute /blob/ URL
     compilation.pdf
   ```

   Verify the blob URL serves the file (open it in a browser, it should show the
   raw image), then verify the rendered sub-page at
   `/<owner>/<slug>/files/<folder>` shows the images, not broken icons.

4. Push it through the git layer, then verify it is really there:

   ```bash
   adom-wiki repo push <owner>/<slug> --files <folder>/README.md <folder>/img/... -m "add <folder> sub-readme"
   adom-wiki repo show <owner>/<slug> <folder>/README.md
   ```

   Content goes through `repo push`, not the raw files API (see `wiki-anatomy`:
   the raw `/files` store and the git page repo are separate, and the Files tab
   renders the git repo).

## Link it from the main README

Point the main README at the sub-readme with a **relative** link to the folder's
`README.md`. Relative paths resolve against the repo, the same way relative image
paths do:

```markdown
## Team docs
- [September DC Kickoff plan](september-dc-event/README.md)
- [Aug 4 meeting recap](virtual-meeting-04aug2026/README.md)
```

## Rules of thumb

- **Absolute `/blob/` URLs for every image and asset.** Relative paths break in
  the Files-tab render (see step 3). This is the single most common sub-readme
  mistake: the doc reads fine as raw markdown and in the root README, then every
  image is a broken icon on the actual sub-page.
- **Links to other wiki PAGES stay normal** (`https://wiki.adom.inc/<owner>/<slug>`);
  only files (images, PDFs, videos) need the `/blob/` treatment.
- **One folder, one topic.** If a doc grows its own images, decks, and sub-docs,
  a folder keeps it tidy and portable.
- **Verify on the rendered sub-page**, not just the raw markdown: open
  `/<owner>/<slug>/files/<folder>` and confirm the images actually load.
- **Markdown only** gets the sanitizer treatment (see `wiki-readme`): prose,
  images, tables, task lists. For a fully designed layout, a sub-readme can be a
  `readme.html`-style file too, but plain `README.md` is the common case.
- **No em-dashes or en-dashes** in wiki prose (house style).