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. That address is what turns this shelf into a directory of everything on the domain, so give it one wherever there is one to give. An app with no url simply shows no link, which is the safe default.
If the app is reached more than one way, add a links list beside the
url — each entry a url and a label. The url stays the app’s front door
and is shown first; the links follow it on the same row. Traveller’s Tales
is the example: the site itself, the uploader at upload.traveller.org, and
the admin at www.traveller.org/admin. Three doors onto one app, one card.
"url": "https://www.traveller.org/",
"urlLabel": "www.traveller.org",
"links": [
{ "url": "https://upload.traveller.org/", "label": "upload.traveller.org" },
{ "url": "https://www.traveller.org/admin/", "label": "www.traveller.org/admin" }
]
If the app is reached by email — a mailbox it accepts things at, the way
Paprika Recipes does — put the address in email rather than url. It
appears in the same chip on the card, printed to be read and copied.
Never write it as a mailto: link. A mailto hands the reader over to
whatever their computer thinks is their mail program, which on a borrowed or
shared machine is the wrong account and often nothing at all; the address
written out works from wherever they actually keep their mail. An app with
several mailboxes uses an emails list instead.
Commit and push.
A word about those addresses. Several of these apps have no password at all:
anyone who knows where they live can use them. They are written on the cards
only because this shelf has a door — since 14 September 2026 it sits behind
Cloudflare Access, and only the people on its allow-list ever see a card. The
test site is a different matter: it runs on GitHub Pages, which cannot have that
door, so a test build shows every card and shows no address on any of them. You
do not have to remember this; it happens on its own. But if the door on the live
shelf is ever taken off, the addresses have to come out of guides.json in the
same change — otherwise removing one lock publishes the keys to the rest.
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.