The five steps that take a new app's guides from its own repository to this shelf — written down here because they are exactly the kind of thing that gets forgotten.
www.traveller.org/guides/ shows one card for every app on the domain, and behind each card that app’s guide — pages written for the person using the app, kept as markdown files in the app’s own repository. Once a night this site copies every app’s pages in and rebuilds; nothing is fetched live, so a repository that is unreachable one night costs nothing — the shelf keeps the last good copy.
Adding a new app is five steps, and the fifth is nothing at all. The first two are repeated whenever a guide changes; three and four happen once per app and take a minute each; the fifth happens by itself. None of them needs a terminal: steps 2, 3 and 4 are all done on github.com in a browser, and step 1 — the only one that touches files — can be handed to Claude whole with the prompt at the bottom of this page.
Every page of a guide is one markdown file in the app’s own repository. The shelf shows an app as soon as it has one page, and takes it off again if the folder is ever deleted.
What you do, in the app’s repository:
Create the folder docs/guides/.
Add one .md file per page. The file’s name becomes the page’s address.
Start each file with this header — only title is required (order sorts
the pages, summary is the line under the title on the app’s landing page):
---
title: Sending photographs from your phone
order: 3
summary: One line for the app's contents page.
---
Put pictures in a sub-folder beside the pages (docs/guides/img/…) and
reference them relatively: .
Commit and push.
The shelf only shows apps named in its manifest. The apps the domain had in September 2026 are already listed, so for those this step is done.
What you do, in the traveller.org repository:
Open src/data/guides.json.
Copy any existing row and change its four values: the slug (which
becomes the address, /guides/<slug>/), the display name on the card,
the repo, and the path — the folder from step 1, normally
docs/guides.
Optionally give it a color — the band its name sits on, on the shelf
and in the list down the left. Any dark colour written as "#1E4FB8"
works; it must be dark enough for white lettering to read against it.
Leave it out and the app is given one automatically, so this is a
preference, not a chore.
Give it a description — one sentence saying what the app is for. Every card on the shelf carries one; it is what makes the page a directory rather than a list of file names.
If the app has an address a person can open — a website, or a mailbox it
accepts mail at — add it as url, with urlLabel for the wording on
the button. If it has more than one address worth opening, add a
links list beside it — one { "url": …, "label": … } per address — and
the card shows them all, url first. This site uses it:
www.traveller.org for the site and upload.traveller.org for the
uploader. An app with one address carries on using url alone.
An app with neither simply shows no link, which is the safe default.
The addresses are only on the cards because this shelf has a door.
Several of these apps have no password of their own: anyone who knows where
they live can use them. Since 14 September 2026 /guides* sits behind
Cloudflare Access with an allow-list, which is what makes publishing them
here reasonable — and the test site, which cannot have that door, strips
every card address at build time. If the Access application ever comes off,
the addresses come off with it.
Commit and push.
The nightly copy reads each app’s repository with a token called
CENTRAL_DOCS_GIT_TOKEN, and that token only reaches the repositories it
has been told about. A repository it cannot see looks exactly like one with no
guides — nothing fails, nothing appears.
What you do, on github.com (once per new app):
If the token has expired instead (they last a year at most, and the sync starts failing with 401): make a new one at the same place — Contents: Read-only on the app repositories, nothing else — and save its value on the traveller.org repository at Settings → Secrets and variables → Actions, under the same name.
Without this step a pushed guide reaches the shelf overnight, which is usually fine. With it, the shelf hears about a push within a minute. Every repository being tracked was given this in September 2026, so it is only needed for genuinely new ones.
What you do, in the app’s repository:
Add these three lines to any of its workflows:
- run: gh api repos/brarob100/traveller.org/dispatches -f event_type=guides-updated
env:
GH_TOKEN: ${{ secrets.CENTRAL_DOCS_DISPATCH }}
Go to the repository’s Settings → Secrets and variables → Actions → New
repository secret, name it CENTRAL_DOCS_DISPATCH, and paste the
shared value — the same one every tracked repository holds. It is scoped to
traveller.org alone and can only ring this bell.
Since 7 September 2026 you do not press anything. The sync copies the pages in and then publishes them to the live shelf itself, usually within a few minutes of the push.
There is one condition, and it protects you: it publishes only when those guide pages are the only thing waiting to go live. If anything else is pending on the site — a change someone is still working on — the sync leaves everything on the test site and says so in its run, because publishing sends the whole site live at once. The guide then goes out with the next ordinary Publish.
What you do:
A guide for an app that changes daily is worse than no guide: it will be wrong by the time someone reads it, and they will not know which half to trust. So an app can be held — its pages stay in its own repository, and the shelf pretends it is not there. No card, no entry in the list down the left, no pages, and the nightly copy stops fetching it. It is not counted among the apps waiting for a first guide either, because it has one.
What you do, in the traveller.org repository:
src/data/guides.json and find the app’s row."hold": "why, and when", — the text is for whoever reads
it next, so say what you are waiting for.To bring it back, delete that line and run the Sync app guides workflow. Its pages are still in its own repository, exactly as they were.
Either end works alone. Delete the app’s docs/guides folder and the next
sync removes its card — or remove its row from src/data/guides.json to stop
tracking it at all. The guides stay in the app’s own repository either way;
the shelf only ever holds a copy.
You never have to open a terminal for any of this. Start a Claude Code session on the new app’s repository (claude.ai/code → new session → pick the repository) and paste the prompt below. It has Claude write the guide, show you every page before anything is pushed, wire up the one-minute ping, and end by telling you the one thing only you can do — step 3, which is a minute of clicking on github.com, no terminal involved. Step 2 stays yours or Claude’s, whichever is easier on the day.
Attach this app to the centralized documentation — the guides shelf at
www.traveller.org/guides, whose machinery lives in the brarob100/traveller.org
repository.
1. Read this repository and work out what the app does and who uses it. If
either is unclear, ask me before writing — a guide that describes the
wrong thing is worse than no guide.
2. Write the app's end-user guide as docs/guides/*.md in THIS repository.
Each file starts with frontmatter: title (required); order and summary
(optional). Images go in a sub-folder beside the pages and are referenced
relatively, like ./img/thing.png. Write for the person USING the app —
what they see, what to tap, what happens next, and what to do when it
doesn't. Plain sentences, no jargon, no implementation detail. The shelf
is readable by anyone with the address, so nothing private: no passwords,
no keys, no private addresses.
3. Show me every page in full before pushing anything. When I approve,
commit to this repository's default branch — tell me if it is protected
and you used another. Never open a pull request.
4. Add a step to one of this repository's workflows (create a minimal one if
there are none) so a push here reaches the shelf within a minute:
- run: gh api repos/brarob100/traveller.org/dispatches -f event_type=guides-updated
env:
GH_TOKEN: ${{ secrets.CENTRAL_DOCS_DISPATCH }}
If the CENTRAL_DOCS_DISPATCH secret is not in this repository's Actions
secrets yet, say so — creating it is mine to do.
5. If you can attach the brarob100/traveller.org repository from this
session, add this app's row to src/data/guides.json there (slug, name,
repo, and path: docs/guides — copy an existing row) and push it. If you
cannot, print the exact row for me to paste on github.com instead.
6. Finish by reminding me of the one step only I can do, with these exact
clicks: github.com → my avatar (top right) → Settings → Developer
settings (bottom of the left-hand list) → Personal access tokens →
Fine-grained tokens → open the CENTRAL_DOCS_GIT_TOKEN token → Repository
access → add this repository. Until I do that, the nightly sync cannot
see this repository and the shelf will not change.