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

Merged

yuris merged 2 commits from docs/wiki-migration into main

2026-08-21 01:39:23 +00:00

yuris commented

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

Owner

Closes #74.

README.md was 1840 lines serving three unrelated audiences at once. The
documentation now lives in the repository wiki as seven flat pages, and this
README.md is a repo description that points at them.

What is here

Only README.md changes in this pull request. The wiki content was pushed
separately to spacetimedb-defold.wiki.git on main, because a wiki is a
distinct git repository and cannot travel in a code pull request.

Wiki layout

Page	Audience
Home	orientation and navigation
Installation	dependency URLs, tag pinning, private-repo tokens, the HTML5 patch
Quickstart	zero to a running client
Usage Guide	callbacks, handles, subscriptions, reconnect, identity, schema, row types
API Reference	every function and table, on one ctrl-F-able page
Protocol Notes	why the wire looks the way it does; not needed in order to ship
Development	repo layout, dev commands, fixture regeneration

Why seven pages and not thirteen

The Forgejo/Gitea wiki has no full-text search. Splitting 1840 lines across a
dozen pages would make the content harder to use than the single file was, so
related material stays together on long pages that ctrl-F well. Two further
constraints came out of services/wiki/wiki_path.go at Gitea v1.22.6, the
version this host is built on:

Wiki pages cannot live in subdirectories — WebPathFromRequest rewrites /
to %2F, and go-gitea#823 has been open since 2017. Page names are flat.
A - in a wiki filename displays as a space, so Usage-Guide.md renders as
"Usage Guide".

One more, found the hard way: the wiki branch is main. Content pushed to
master is silently invisible to Forgejo, reported by both the web UI and
/api/v1/repos/…/wiki/pages as an empty wiki. A stale master ref on the wiki
repo has been deleted.

Verification

Every section of the old README landed on exactly one wiki page; the move was
verbatim apart from heading levels and link rewrites.
Cross-page anchors were remapped; remaining same-page anchors were checked
mechanically against each page's own slugified headings.
.gitattributes is unchanged, so the release archive still carries
README.md — now a much smaller member.

Licence and disclaimer

This branch also adds a LICENSE file — MIT, (c) 2026 Yuris Cakranegara — since
the repository declared no licence at all. README.md gains a short disclaimer:
an independent project, not affiliated with Clockwork Labs, and the MIT grant
covers this SDK only, not SpacetimeDB (BSL 1.1 at the pinned version).

LICENSE is not export-ignored, so the release archive now enumerates 13
entries instead of 12. Both .gitattributes and the wiki Development page were
corrected to say so.

Closes #74. `README.md` was 1840 lines serving three unrelated audiences at once. The documentation now lives in the repository wiki as seven flat pages, and this `README.md` is a repo description that points at them. ## What is here Only `README.md` changes in this pull request. The wiki content was pushed separately to `spacetimedb-defold.wiki.git` on `main`, because a wiki is a distinct git repository and cannot travel in a code pull request. ## Wiki layout | Page | Audience | |---|---| | Home | orientation and navigation | | Installation | dependency URLs, tag pinning, private-repo tokens, the HTML5 patch | | Quickstart | zero to a running client | | Usage Guide | callbacks, handles, subscriptions, reconnect, identity, schema, row types | | API Reference | every function and table, on one ctrl-F-able page | | Protocol Notes | why the wire looks the way it does; not needed in order to ship | | Development | repo layout, dev commands, fixture regeneration | ## Why seven pages and not thirteen The Forgejo/Gitea wiki has no full-text search. Splitting 1840 lines across a dozen pages would make the content harder to use than the single file was, so related material stays together on long pages that ctrl-F well. Two further constraints came out of `services/wiki/wiki_path.go` at Gitea v1.22.6, the version this host is built on: - Wiki pages cannot live in subdirectories — `WebPathFromRequest` rewrites `/` to `%2F`, and go-gitea#823 has been open since 2017. Page names are flat. - A `-` in a wiki filename displays as a space, so `Usage-Guide.md` renders as "Usage Guide". One more, found the hard way: the wiki branch is `main`. Content pushed to `master` is silently invisible to Forgejo, reported by both the web UI and `/api/v1/repos/…/wiki/pages` as an empty wiki. A stale `master` ref on the wiki repo has been deleted. ## Verification - Every section of the old README landed on exactly one wiki page; the move was verbatim apart from heading levels and link rewrites. - Cross-page anchors were remapped; remaining same-page anchors were checked mechanically against each page's own slugified headings. - `.gitattributes` is unchanged, so the release archive still carries `README.md` — now a much smaller member. ## Licence and disclaimer This branch also adds a `LICENSE` file — MIT, (c) 2026 Yuris Cakranegara — since the repository declared no licence at all. `README.md` gains a short disclaimer: an independent project, not affiliated with Clockwork Labs, and the MIT grant covers this SDK only, not SpacetimeDB (BSL 1.1 at the pinned version). `LICENSE` is not export-ignored, so the release archive now enumerates 13 entries instead of 12. Both `.gitattributes` and the wiki Development page were corrected to say so.

yuris added 1 commit

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

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

ci / ci (pull_request) Successful in 1m30s

Details

86b0eacb20

yuris force-pushed docs/wiki-migration from 86b0eacb20

ci / ci (pull_request) Successful in 1m30s

Details

to 4d21089f4a

ci / ci (pull_request) Successful in 20s

Details