docs: hand the landing-page role from the README to maka.apache.org - #4686
Draft
Astro-Han wants to merge 4 commits into
Draft
docs: hand the landing-page role from the README to maka.apache.org#4686Astro-Han wants to merge 4 commits into
Astro-Han wants to merge 4 commits into
Conversation
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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdand the.asf.yamldescription 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 andARCHITECTURE.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 awebsite/line in the layout and a website link in Documentation. Both languages stay section-for-section identical.website/scripts/readme-hero.mjs(run withnpm --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, anddocs/code-origin-audit.mdnow records that the heroes are renders of the site's own copy and styles rather than generated art.ARCHITECTURE.mdlinks four deep dives, not six, so the README stops counting; and the repository layout gainsnative/,skills/,patches/andexperiments/.website/test/site.test.mjsasserts 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.yamlkeeps its existing release-contract lane.git showand 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
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 onmain; 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.AI use
Select exactly one:
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
Does this PR entail a change in behavior?