xonecas.io
8356
Wx

www-xonecas-io / commit 2ae8f03

a README on using the site, managing repos and the code layout (1044)

Co-Authored-By: Claude Opus 5.5

Sean Caetano Martin2026-11-08 2ae8f03edf4cbe2af8c3e47510f8a0a0be4e8311 parent 68b097e

2 files changed

README.md+63−0
@@ -0,0 +1,63 @@
1+# xonecas.io
2+
3+My projects and their git history, as a static site. It reads git repos and renders `public/`, which any static
4+server can host, including the `<name>.git` folders you `git clone` from.
5+
6+```
7+ bin/site remote new ─► git push ─► repos/xonecas.io/<name>.git ──┐
8+ ├─► site index ─► site build ─► public/
9+ sources.txt ─► site import ─► repos/<host>/<owner>/<repo>.git ───┤
10+ overrides.txt ──┘
11+```
12+
13+## Start
14+
15+```sh
16+make site # builds bin/site
17+make import # mirrors every repo in sources.txt into repos/
18+make index # reads repos/ into data/projects.json
19+make serve # builds public/ and serves it on http://vm:8080
20+```
21+
22+Run everything from this folder. `bin/site help` lists the commands, and `bin/site <command> -h` lists a command's flags.
23+
24+## Manage repos
25+
26+| To | Run |
27+| --- | --- |
28+| Start a repo the site hosts | `bin/site remote new my-thing`, then the `git remote add` line it prints, then `git push -u origin main` |
29+| Show a repo you already have | `bin/site remote add ~/code/other-thing` (a path) or `bin/site remote add https://host/owner/repo.git` |
30+| Stop showing a repo | `bin/site remote rm <path or url>` (a hosted repo's data is kept) |
31+| List the repos | `bin/site remote list` |
32+| Fetch every added repo again | `make import` |
33+| Rebuild the site | `make index build` |
34+
35+A push to a hosted repo rebuilds `public/` by itself; its log is `repos/xonecas.io/<name>.git/build.log`.
36+After `remote add` or `rm`, run `make index build`.
37+
38+`repos/` is git-ignored. On the VM it is lost when the VM is recreated, so host repos on the machine that serves the site.
39+
40+## Fix how a project shows
41+
42+Edit `overrides.txt`, one rule per line, then `make index build`:
43+
44+```
45+merge <remote URL> <remote URL> make two remotes one project
46+rename <name> <new name> rename a project
47+hide <name> hide a project
48+show <name> list a fork or an empty repo, which are hidden by default
49+tag <name> +frontend -backend add or drop tags
50+```
51+
52+## Layout
53+
54+| Path | Holds |
55+| --- | --- |
56+| `cmd/site` | the `site` command: import, remote, index, build, serve, help |
57+| `internal/store` | the repo store: `sources.txt`, mirrors, hosted repos, the hosts' metadata |
58+| `internal/project` | groups repos into projects, and their tags, description and overrides |
59+| `internal/site` | renders every page into `public/` |
60+| `internal/repo` | runs git against a bare repo |
61+| `tickets/` | the Rats board |
62+
63+`make test` runs the tests.
tickets/1044-no-readme.md+19−0
@@ -0,0 +1,19 @@
1+---
2+id: 1044
3+title: No README
4+type: chore
5+status: review
6+priority: p2
7+created: 2026-11-08T15:45:06Z
8+updated: 2026-11-08T15:46:39Z
9+source: human
10+area: docs
11+moves: 2026-11-08T15:45:24Z inbox doing drag; 2026-11-08T15:46:39Z doing review agent
12+---
13+
14+
15+## Notes
16+
17+- 2026-11-08 15:45Z (agent): Triage: chore, p2, area docs. This repo has no README.md at its root. Without one, its project page would have no description once 1041 adds it to the site, and the only usage docs are bin/site help (1042). It isn't a bug: nothing is broken. Question: should the README cover only using the site (bin/site, pushing repos, make serve), or also how the code is laid out?
18+
19+- 2026-11-08 15:46Z (agent): Added README.md at the repo root: what the site is, a diagram of push/import → index → build → public/, how to start (make site, import, index, serve), managing repos, overrides.txt rules and the code layout. It closes 1045 too. I picked the scope myself, since the question was open: usage plus a short layout table. Checked: each command and path in it against the Makefile, help and code (make -n index build, remote list gives 105). Not checked: how it renders …