Skip to content

docs: migrate README.md / README.zh-CN.md to a single NRG template - #239

Open
andriishin wants to merge 1 commit into
gookit:masterfrom
andriishin:nrg-migration
Open

docs: migrate README.md / README.zh-CN.md to a single NRG template#239
andriishin wants to merge 1 commit into
gookit:masterfrom
andriishin:nrg-migration

Conversation

@andriishin

Copy link
Copy Markdown

Why

README.md and README.zh-CN.md are hand-maintained side-by-side. Both files are ~1880 lines and follow the same structure section-by-section, so each new package or feature added to the project means editing the same paragraph in two places. Drift between the two is easy to introduce and hard to spot in review.

This PR migrates both files to a single source-of-truth template using Nanolaba Readme Generator (NRG) — a small Java 8 tool that turns one README.src.md into N localized README files. Combined with the bundled GitHub Action nanolaba/nrg-action@v1, regeneration happens in CI on every push to master — no Java toolchain needed locally, no Go-side dependency added, just YAML.

What changes

  • New: README.src.md — the unified source (~3760 lines). Each line is tagged <!--en--> or <!--zh-CN--> so it appears only in that language's output. NRG strips the markers from the final files. The template was generated programmatically from the existing two files: each line of README.<lang>.md got its language marker appended verbatim, and the two streams were concatenated. Regenerated outputs are byte-identical to today's files (modulo a 2-line auto-generated header).
  • New: .github/workflows/nrg.yml — runs nanolaba/nrg-action@v1 (pinned to NRG 1.1):
    • On push to master that touches README.src.md or the workflow file: regenerates and auto-commits any changed READMEs.
    • On PR that touches any of the three files (README.md, README.zh-CN.md, README.src.md): runs in check mode — fails with a unified diff if a contributor edited a generated file instead of regenerating from the template.
  • Modified: README.md (+2 lines), README.zh-CN.md (+2 lines) — regenerated. The only change is the 2-line auto-generated header at the top. Body content is byte-for-byte identical.

The non-default Chinese filename README.zh-CN.md is produced by declaring the language as zh-CN (rather than zh) — NRG's default output pattern <base>.<lang>.md then yields README.zh-CN.md directly, no override needed.

Verification

Locally, regenerating with NRG 1.1 from Maven Central against current master (commit 3d1cd97) produces output that diffs against the originals only by the 2-line auto-generated header on each file. Zero functional content change. Tested with the same nanolaba/nrg-action@v1 setup that the workflow uses (Java 17 + NRG 1.1 from Maven Central).

What's intentionally NOT in this PR

  • Translation alignment. Both files happen to be in lockstep today and the migration preserves that. The auto-generated template uses per-line language markers, which means today's content lives unchanged in README.src.md. Future PRs can extract shared structural elements (badge URLs, table headers, code blocks) into shared regions — incremental, reviewable changes rather than one big rewrite.
  • No Go module impact. Nothing in this PR changes Go code, go.mod, or any build step. Only the README files and a docs workflow.

How to regenerate locally

curl -L -o nrg.jar https://repo1.maven.org/maven2/com/nanolaba/readme-generator/1.1/readme-generator-1.1.jar
java -jar nrg.jar -f README.src.md

(Once the workflow is merged, git push to a branch and CI will do this for you.)

About NRG

com.nanolaba:readme-generator — open-source, Apache 2.0, Java 8+. Ships as a CLI, Maven plugin, GitHub Action, and library. The action approach used here requires zero local toolchain setup — the Java is provisioned by the action itself.

Replace the two hand-maintained README files with a single
README.src.md, regenerated in CI by nanolaba/nrg-action@v1 on each
push to master. The two outputs are byte-for-byte identical to the
originals (modulo a 2-line auto-generated header NRG injects at the
top of every output).

A drift-check job runs on PRs that touch README.src.md or either
generated README, failing the build with a unified diff if a
contributor edited one of the generated files instead of
regenerating it from the template. <check>false</check>-equivalent
for push events keeps the build forgiving until the workflow
settles in.
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