Move documentation into the wiki; shrink README to a repo description #74

New issue

Closed

opened 2026-08-20 17:20:51 +00:00 by yuris · 0 comments

yuris commented

2026-08-20 17:20:51 +00:00

Owner

Goal

README.md is 1841 lines and serves three unrelated audiences at once: people
trying to ship a game, people hunting one specific behaviour, and people
hacking on the repo. Move the documentation into the repository wiki and shrink
README.md to a repo description that points at it.

Constraints, established from source rather than folklore

The wiki host is git.nokopia.com, running Forgejo 15.0.1+gitea-1.22.0.

No subdirectories for pages. services/wiki/wiki_path.go at Gitea
v1.22.6 — the version this Forgejo release is built on — replaces / with
%2F in WebPathFromRequest, and carries two explicit TODOs
(// TODO: support subdirectory in the future, and on UserTitleToWebPath,
// TODO: no support for subdirectory … we do not add the support for writing slashes in title). Corroborated by go-gitea#823, open since 2017 with every
acceptance checkbox unchecked, and an April 2026 report of 500 / Not Found on
markdown links into wiki subdirectories.

→ Page names must be flat.
Dashes in filenames become spaces in titles. escapeSegToWeb /
unescapeSegment: Home-Page.md displays as "Home Page". Keeping a literal
dash requires Gitea's .- DashMarker suffix (Foo-Bar.-.md), which is not
worth hand-writing. Pick filenames knowing the transform.
Reserved page names: _pages, _new, _edit, raw. A path ending in
.md is served as a raw file, so never link a page as Page.md.
The wiki branch is main, not master. Confirmed via the repo API
("wiki_branch": "main"). A push to master is silently invisible — the web
UI and /api/v1/repos/…/wiki/pages both report an empty wiki. There is
currently a stray master ref on spacetimedb-defold.wiki.git from a
probe commit; delete it as part of this work.
There is no wiki search. Stated by a Gitea maintainer on go-gitea#823
alongside the missing-subdirectory admission. Not independently verified for
Forgejo 15, so treat as likely rather than certain — but plan for it, because
it is the constraint that decides page granularity. Without full-text search,
splitting 1841 lines across a dozen pages makes the content harder to use
than one file with ctrl-F.

→ Prefer few large pages over many small ones.

Usable and confirmed from the Forgejo v15 wiki documentation: Home.md as the
entry page, global _Sidebar.md / _Footer.md (hidden from the pages list;
reachable by URL), [[Page]] wiki-links, images committed under images/ via a
git client only, and KaTeX math.

Proposed page tree

Seven pages. Each is independently ctrl-F-able, and the merged usage page keeps
the README's existing intra-page anchors working instead of rewriting roughly
fifteen of them into cross-page links.

Page	Source in current README
`Home`	new, ~30 lines: what this is, SpacetimeDB 2.x / captured against 2.8.2, navigation table, link back to the repo
`Installation`	`## Install` + `### HTML5 needs a patched extension-websocket` — the HTML5 patch is install work, not protocol trivia
`Quickstart`	`## Usage` opening example, expanded into a genuine zero-to-running path: server module, publish, connect, subscribe, call a reducer. The README has no such path today; this is the one materially new page
`Usage Guide`	`### Per-table callbacks`, `### Dropping a subscription`, `### Handles`, `### Procedures`, `### Reconnect`, `### Identity persistence`, `### Authenticating with a provider`, `### Generating the schema`, `### Views`, `### Relations your schema does not describe`, `### Row value types` — one long page, `##` per section
`API Reference`	`## API reference` and all subsections, including `#### Special types and their units`. One page; reference material wants ctrl-F, not navigation
`Protocol Notes`	`## Protocol reality check` + `### Three Defold-specific traps` — why the wire looks the way it does; nothing here is needed in order to ship
`Development`	`## Layout`, `## Dev`, `## Regenerating fixtures`, `### No docker` — contributors only

Plus _Sidebar.md carrying the same seven links, since without search the
navigation is load-bearing.

What `README.md` keeps

A repo description, not a summary of the wiki:

What it is: SpacetimeDB 2.x client SDK for Defold, in Lua
The two game.project dependency URLs, because a reader who wants only that
should not need a second page load
A link to the wiki, and one line on what lives there
Licence, and the repo layout note that dev/ is stripped from the release
archive

Target: under 60 lines.

Acceptance

Seven pages exist on the wiki's main branch, flat names, no subdirectories
Every section of the current README appears on exactly one page, or is
deliberately dropped with the reason recorded in this issue
No cross-page link resolves to a "create this page" prompt
All intra-page anchors that survive the move still resolve; anchors
crossing a page boundary are rewritten to page links
_Sidebar.md lists all seven pages
README.md is under 60 lines and links to the wiki
The stray master ref on spacetimedb-defold.wiki.git is deleted
The release archive still carries the shortened README.md
(.gitattributes is unchanged; verify with git archive)

Deliberately out of scope

Generating the wiki from the README, or the reverse. Two copies drift; the
README becoming a stub is what removes the duplication.
A troubleshooting page. Every error string is already documented next to the
code that produces it.
Per-page sidebars. Reported to work on GitHub wikis, unverified on Forgejo,
and unnecessary at seven pages.

## Goal `README.md` is 1841 lines and serves three unrelated audiences at once: people trying to ship a game, people hunting one specific behaviour, and people hacking on the repo. Move the documentation into the repository wiki and shrink `README.md` to a repo description that points at it. ## Constraints, established from source rather than folklore The wiki host is `git.nokopia.com`, running Forgejo `15.0.1+gitea-1.22.0`. 1. **No subdirectories for pages.** `services/wiki/wiki_path.go` at Gitea `v1.22.6` — the version this Forgejo release is built on — replaces `/` with `%2F` in `WebPathFromRequest`, and carries two explicit TODOs (`// TODO: support subdirectory in the future`, and on `UserTitleToWebPath`, `// TODO: no support for subdirectory … we do not add the support for writing slashes in title`). Corroborated by go-gitea#823, open since 2017 with every acceptance checkbox unchecked, and an April 2026 report of 500 / Not Found on markdown links into wiki subdirectories. → **Page names must be flat.** 2. **Dashes in filenames become spaces in titles.** `escapeSegToWeb` / `unescapeSegment`: `Home-Page.md` displays as "Home Page". Keeping a literal dash requires Gitea's `.-` DashMarker suffix (`Foo-Bar.-.md`), which is not worth hand-writing. Pick filenames knowing the transform. 3. **Reserved page names:** `_pages`, `_new`, `_edit`, `raw`. A path ending in `.md` is served as a raw file, so never link a page as `Page.md`. 4. **The wiki branch is `main`, not `master`.** Confirmed via the repo API (`"wiki_branch": "main"`). A push to `master` is silently invisible — the web UI and `/api/v1/repos/…/wiki/pages` both report an empty wiki. There is currently a stray `master` ref on `spacetimedb-defold.wiki.git` from a probe commit; delete it as part of this work. 5. **There is no wiki search.** Stated by a Gitea maintainer on go-gitea#823 alongside the missing-subdirectory admission. Not independently verified for Forgejo 15, so treat as likely rather than certain — but plan for it, because it is the constraint that decides page granularity. Without full-text search, splitting 1841 lines across a dozen pages makes the content *harder* to use than one file with ctrl-F. → **Prefer few large pages over many small ones.** Usable and confirmed from the Forgejo v15 wiki documentation: `Home.md` as the entry page, global `_Sidebar.md` / `_Footer.md` (hidden from the pages list; reachable by URL), `[[Page]]` wiki-links, images committed under `images/` via a git client only, and KaTeX math. ## Proposed page tree Seven pages. Each is independently ctrl-F-able, and the merged usage page keeps the README's existing intra-page anchors working instead of rewriting roughly fifteen of them into cross-page links. | Page | Source in current README | |---|---| | `Home` | new, ~30 lines: what this is, SpacetimeDB 2.x / captured against 2.8.2, navigation table, link back to the repo | | `Installation` | `## Install` + `### HTML5 needs a patched extension-websocket` — the HTML5 patch is install work, not protocol trivia | | `Quickstart` | `## Usage` opening example, expanded into a genuine zero-to-running path: server module, publish, connect, subscribe, call a reducer. The README has no such path today; this is the one materially new page | | `Usage Guide` | `### Per-table callbacks`, `### Dropping a subscription`, `### Handles`, `### Procedures`, `### Reconnect`, `### Identity persistence`, `### Authenticating with a provider`, `### Generating the schema`, `### Views`, `### Relations your schema does not describe`, `### Row value types` — one long page, `##` per section | | `API Reference` | `## API reference` and all subsections, including `#### Special types and their units`. One page; reference material wants ctrl-F, not navigation | | `Protocol Notes` | `## Protocol reality check` + `### Three Defold-specific traps` — why the wire looks the way it does; nothing here is needed in order to ship | | `Development` | `## Layout`, `## Dev`, `## Regenerating fixtures`, `### No docker` — contributors only | Plus `_Sidebar.md` carrying the same seven links, since without search the navigation is load-bearing. ## What `README.md` keeps A repo description, not a summary of the wiki: - What it is: SpacetimeDB 2.x client SDK for Defold, in Lua - The two `game.project` dependency URLs, because a reader who wants only that should not need a second page load - A link to the wiki, and one line on what lives there - Licence, and the repo layout note that `dev/` is stripped from the release archive Target: under 60 lines. ## Acceptance - [ ] Seven pages exist on the wiki's `main` branch, flat names, no subdirectories - [ ] Every section of the current README appears on exactly one page, or is deliberately dropped with the reason recorded in this issue - [ ] No cross-page link resolves to a "create this page" prompt - [ ] All intra-page anchors that survive the move still resolve; anchors crossing a page boundary are rewritten to page links - [ ] `_Sidebar.md` lists all seven pages - [ ] `README.md` is under 60 lines and links to the wiki - [ ] The stray `master` ref on `spacetimedb-defold.wiki.git` is deleted - [ ] The release archive still carries the shortened `README.md` (`.gitattributes` is unchanged; verify with `git archive`) ## Deliberately out of scope - Generating the wiki from the README, or the reverse. Two copies drift; the README becoming a stub is what removes the duplication. - A troubleshooting page. Every error string is already documented next to the code that produces it. - Per-page sidebars. Reported to work on GitHub wikis, unverified on Forgejo, and unnecessary at seven pages.

yuris referenced this issue from a commit

2026-08-20 17:26:18 +00:00

docs: shrink README to a repo description (#74)

yuris referenced this issue from a commit

2026-08-20 17:34:20 +00:00

docs: shrink README to a repo description (#74)

yuris referenced this issue from a pull request that will close it,

2026-08-20 17:34:27 +00:00

docs: move documentation into the wiki, shrink README to a repo description #75

yuris referenced this issue from a commit

2026-08-21 01:26:21 +00:00

docs: shrink README to a repo description (#74)