Skip to content

docs: split README into a leaner top page + topic docs#13

Merged
avanelsas merged 2 commits intomainfrom
docs/split-readme
Apr 30, 2026
Merged

docs: split README into a leaner top page + topic docs#13
avanelsas merged 2 commits intomainfrom
docs/split-readme

Conversation

@avanelsas
Copy link
Copy Markdown
Owner

Summary

The README had grown to 677 lines, with three sections (Recipes,
Adding-a-new-BareDOM-component, Project-layout) taking up two-thirds
of the file. First-time visitors landing on the README for "what
is this" or "how do I run it" had to scroll past almost half of a
long-form walkthrough they didn't ask for.

This PR pulls the deep-dive content into the existing `docs/`
directory (which already houses `architecture.md` and
`plugins.md`) and gives the README a new `## Docs` section
between Features and Authoring shortcuts with one-line pointers to
the four docs.

What moved

From README To Lines
Recipes (walkthrough + quick ref) `docs/recipes.md` (new) 335
Adding a new BareDOM component `docs/adding-components.md` (new) 75
Project layout folded into `docs/architecture.md` 36

What stayed

Marketing hook sections — Why Bareforge?, Features, Authoring
shortcuts (the v0.2.0 highlight), Fields & bindings, Templates,
Status, Quick start, Philosophy, Contributing — plus the new
`## Docs` section. README is now 246 lines (down 64%) while
keeping every user-facing top-of-funnel feature mention.

Link integrity

  • The walkthrough's `Fields & bindings` link
    rewrites to `../README.md#fields--bindings` so it still
    resolves on GitHub.
  • Fixture paths in the walkthrough (e.g.
    `test/fixtures/export/demo-store-with-bindings.json`) gain a
    `../` prefix.
  • The Features bullet that pointed at the in-README `#recipes`
    anchor now points at `docs/recipes.md`.
  • All four `docs/*.md` links in the new `## Docs` section
    resolve.

Test plan

This is a documentation refactor — no code changes. Standard gates
re-run as muscle memory:

  • `cljfmt check` — all source files formatted correctly.
  • `npx shadow-cljs compile test` — 571 tests, 0 failures.
  • `npx shadow-cljs release app` — 0 warnings under Closure Advanced.
  • `clj-kondo --lint src test scripts` — 0 errors, 0 warnings.

Render-side checks worth doing post-merge:

  • Open the rendered `README.md` on github.com — `## Docs`
    bullets resolve, all section anchors work.
  • Open `docs/recipes.md` — internal step links land, fixture
    paths resolve, the back-link to `../README.md#fields--bindings`
    jumps to the right anchor.
  • Open `docs/adding-components.md` — renders cleanly.
  • Open `docs/architecture.md` — the appended Project layout
    section sits before "Where to read next".

🤖 Generated with Claude Code

avanelsas and others added 2 commits April 30, 2026 10:34
The README had grown to 677 lines, with three sections taking up
two-thirds of it. A first-time visitor scrolling for "what is this"
or "how do I run it" had to load almost half of a long-form
walkthrough they didn't ask for.

Three sections move into the existing docs/ directory:

- Recipes (335 lines) → docs/recipes.md. The eleven-step
  product-feed walkthrough plus the quick-reference index. The
  walkthrough's `[Fields & bindings](#fields--bindings)` link
  rewrites to `../README.md#fields--bindings` so it still resolves
  on GitHub. Fixture paths gain `../` prefixes.
- Adding a new BareDOM component (75 lines) → docs/adding-
  components.md. Recipe + what-it-touches + optional polish + how-
  it-works as a contributor onboarding doc. No relative links
  needed adjustment.
- Project layout (36 lines) → folded into the existing
  docs/architecture.md before its "Where to read next" outro,
  alongside the doc references it already lists.

The README gains a new `## Docs` section between Features and
Authoring shortcuts (the user-chosen TOC strategy), with bulleted
links to all four docs/. The Features section's existing pointer
into the walkthrough re-targets `docs/recipes.md`.

README is now 246 lines (was 677, down 64%). No code changes;
gates green for muscle-memory:

- cljfmt check — all source files formatted correctly.
- npx shadow-cljs compile test — 571 tests, 0 failures.
- npx shadow-cljs release app — 0 warnings.
- clj-kondo — 0 errors, 0 warnings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The rule lived as a sub-paragraph inside `PR readiness gate`, which
is easy to skim past — and was missed in this very session when the
README-split PR went straight from plan-approval to `gh pr create`.

Pulling it out into its own top-level section between `PR readiness
gate` and `After a PR is merged`, and adding the clauses that close
the loopholes I'd been tripping on:

- **Plan approval is not PR approval.** Approving a plan via
  ExitPlanMode authorises writing the code, not opening the PR.
- **All-gates-green is not approval.** Cljfmt + tests + release +
  lint passing means the branch is ready for review, not that the
  reviewer wants the review request fired right now.
- **A previous PR's approval is not blanket approval.** Each PR
  needs its own go-ahead.
- **Auto mode does not override this.** Auto mode is for
  minimising interruptions on local, reversible work; PR creation
  is shared-state and explicitly excluded.

Plus a clear what-to-do-instead checklist (push the branch first
— that's fine — summarise gate results, ask, wait for yes, then
run `gh pr create`).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@avanelsas avanelsas merged commit 9a237ab into main Apr 30, 2026
1 check passed
@avanelsas avanelsas deleted the docs/split-readme branch April 30, 2026 08:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant