Skip to content

docs: hand the landing-page role from the README to maka.apache.org - #4686

Draft
Astro-Han wants to merge 4 commits into
mainfrom
docs/4684-readme-handoff
Draft

docs: hand the landing-page role from the README to maka.apache.org#4686
Astro-Han wants to merge 4 commits into
mainfrom
docs/4684-readme-handoff

Conversation

@Astro-Han

@Astro-Han Astro-Han commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Since #4660 the website is the landing page and the downloads path, but both READMEs still ran 290 lines as landing page, install guide and architecture summary, and opened with a different sentence from the site and the repository description.

  • README.md, README.zh-CN.md and the .asf.yaml description carry the sentence settled in [DISCUSS] Rebuild the Maka website and project narrative #4307. The header is title, badges and hero; the hero carries the headline, so the sentence and lede appear once, as text opening "What Maka is". That section replaces "Why Maka", "Surfaces" and "Current capabilities" with the site's four claims (measured not claimed, the log is the runtime, your machine and your model, one Runtime Host) and a sentence linking the site and ARCHITECTURE.md. "Releases and downloads" becomes "Get Maka" with the same three labelled paths as the downloads page and links there instead of to GitHub Releases. Requirements, start and first run move under "Build from source". Website and Downloads are badges in the style of the row above them. The rest of the README is unchanged apart from a website/ line in the layout and a website link in Documentation. Both languages stay section-for-section identical.
  • The hero is rendered from the website itself: website/scripts/readme-hero.mjs (run with npm --workspace @maka/website run readme-hero) builds the site and screenshots the homepage headline and RuntimeEvents scene per language and colour scheme into .github/assets/readme-hero.*.png, and the READMEs pick light or dark with a <picture> element. The two per-language illustrations that baked in the old tagline are removed, and docs/code-origin-audit.md now records that the heroes are renders of the site's own copy and styles rather than generated art.
  • Every retained claim was checked against the repository. Three were stale and are corrected: Desktop Nightly has published macOS arm64 and x64, Windows x64 and Linux x64 and arm64 builds for some time, but the README and the website's three platform lines said Apple Silicon only with a Windows preview, so both now name the full matrix with Windows and Linux as unsigned previews; ARCHITECTURE.md links four deep dives, not six, so the README stops counting; and the repository layout gains native/, skills/, patches/ and experiments/.
  • website/test/site.test.mjs asserts the two READMEs and the description carry the sentence, and the CI planner runs the website workspace for a README change so the check runs when it matters. .asf.yaml keeps its existing release-contract lane.
  • Committing the first version of this branch showed that the pre-commit Biome check from feat(ci): add fast local validation hooks #4132 could not commit a binary or a Markdown file: it pipes every staged blob through git show and Biome with Node's default 1 MiB buffer, Biome rejects stdin that is not UTF-8, and for a language it parses without formatting it echoes nothing, which the hook read as unformatted. Binaries are now skipped by git's NUL-byte heuristic, an empty echo is treated as no handler, and the buffer limits are lifted, with a test for each.

Fixes #4684

Old and new README hero

Verification

  • npm --workspace @maka/website run test:dist: 9/9, including the new cross-surface sentence test.
  • npm --workspace @maka/website run readme-hero: writes the four PNGs above from the built site.
  • node --test scripts/ci-test-plan.test.mjs scripts/ci-workflow-policy.test.mjs scripts/biome-staged-check.test.mjs: 80/80. The new planner test and the hook's binary and Markdown cases fail on main; the first two commit attempts of this branch failed on exactly those two hook paths.
  • npm run format, npm run lint, npm run check:asf-headers: clean.
  • Scripted check that every relative link and image path in both READMEs exists and the two in-page anchors match a heading; both files have the same 13 headings in the same order.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code set the section skeleton, wrote the render script, the tests, the planner and hook changes and this description; Gemini 3.8 Flash (Antigravity CLI) drafted the README prose from that skeleton, which I then corrected against the site copy and cut back to bullets. I reviewed every line of both READMEs.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

Since #4660 the website is the landing page and the downloads path, but
both READMEs still ran 290 lines as landing page, install guide and
architecture summary, and opened with a different sentence from the site
and the repository description. The READMEs and the .asf.yaml description
now open with the sentence settled in #4307; "Why Maka", "Surfaces" and
"Current capabilities" become one section of three paragraphs that link
the site, ARCHITECTURE.md and docs/README.md; "Releases and downloads"
becomes "Get Maka" with the same three labelled paths as the downloads
page, and the requirements, start and first-run steps move under "Build
from source". The website test now asserts the three surfaces carry the
sentence, and the CI planner runs the website workspace for README
changes so that check has teeth.

The hero is one text-free image for both languages, generated with
Codex's image tool from a text prompt in the mascot's existing style,
replacing the two per-language images that baked in the old tagline.
The provenance record lists the new file and how it was made.

Committing this showed that the pre-commit Biome check from #4132 could
not commit a binary or a Markdown file: it pipes every staged blob
through git show and Biome with Node's default 1 MiB buffer, Biome
rejects stdin that is not UTF-8, and for a language it parses without
formatting it echoes nothing, which the hook read as unformatted.
Binaries are skipped by git's NUL-byte heuristic, an empty echo is
treated as no handler, and the buffer limits are lifted.

Refs #4684

Generated-by: Claude Code
@github-actions github-actions Bot added the effort/M Under 500 readable lines label Sep 3, 2026
The mascot illustration did not look like the site the README now hands
off to, so the hero is rendered from the built website instead:
website/scripts/readme-hero.mjs screenshots the homepage headline and
the RuntimeEvents scene per language and colour scheme, and the READMEs
pick light or dark with a picture element. The generated illustration is
removed and the provenance record says the heroes are renders of the
site's own copy and styles, not generated art.

The Website and Downloads links become badges in the style of the row
above them, and "What Maka is" goes back to four short bullets and one
linking sentence; the three dense paragraphs read worse than the list
they replaced.

Generated-by: Claude Code
The hero image already carries the headline, so the bold sentence and
lede above it were the same words twice. The header is now title, badges
and hero; the positioning sentence and lede open "What Maka is" as text,
and the bullets restate the site's four claims (measured, log is the
runtime, local machine and own model, one Runtime Host) instead of the
local-first list the old README led with.

Generated-by: Claude Code
Desktop Nightly has published macOS arm64 and x64, Windows x64 and
Linux x64 and arm64 builds for some time, but the README and the
website's three platform lines still said Apple Silicon only with a
Windows preview; both now name the full matrix, with Windows and Linux
as unsigned previews. ARCHITECTURE.md links four deep dives, not six,
so the README stops counting them, and the repository layout gains the
native/, skills/, patches/ and experiments/ directories it omitted.

Generated-by: Claude Code
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: hand the landing-page role from the README to maka.apache.org

1 participant