Skip to content

docs: migrate README.md / README_ZH.md to a single NRG template - #97

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

docs: migrate README.md / README_ZH.md to a single NRG template#97
andriishin wants to merge 1 commit into
agmmnn:masterfrom
andriishin:nrg-migration

Conversation

@andriishin

Copy link
Copy Markdown

Why

README.md (EN) and README_ZH.md (Chinese) are hand-maintained side-by-side. Both files are ~1180 lines of curated lists with hundreds of entries — every new addition means editing the same paragraph in two places, and drift between the two is easy to introduce.

This PR migrates both files to a single source-of-truth template using Nanolaba Readme Generator (NRG). Combined with the bundled GitHub Action nanolaba/nrg-action@v1, regeneration happens in CI on every push to master — no toolchain needed locally, just YAML.

What changes

  • New: README.src.md — the unified source (~2360 lines). Each line is tagged <!--en--> or <!--zh--> so it appears only in that language's output. The template was generated programmatically by appending each line of README.<lang>.md with its language marker and concatenating the streams. Both 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):
    • Push to master touching README.src.md or the workflow: regenerates and auto-commits any changed READMEs.
    • PR touching any of the three files: drift check in mode: check — fails with a unified diff if a contributor edited a generated file directly.
  • Modified: README.md (+2 lines), README_ZH.md (+2 lines) — regenerated. The only change is the 2-line auto-generated header at the top.

The non-default Chinese filename README_ZH.md (rather than the default README.zh.md) is preserved through <!--@nrg.fileNamePattern.zh=README_ZH.md-->.

Verification

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

What's intentionally NOT in this PR

  • Translation alignment. The auto-generated template uses per-line language markers — today's content lives unchanged in README.src.md. Future PRs can extract shared structural elements (badge URLs, table headers, anchor labels) into shared regions of the template — incremental, reviewable changes.
  • Awesome-list link curation. Nothing in this PR adds, removes, or reorders any list entry. 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

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 — Java is provisioned by the action.

Replaces the two hand-maintained READMEs (~1180 lines each) with a
single README.src.md, regenerated in CI by nanolaba/nrg-action@v1
on push to master. Both outputs are byte-identical to the originals
(modulo a 2-line auto-generated header NRG injects at the top).

Drift-check job runs in mode: check on PRs that touch the template
or either generated README, failing the build with a unified diff
when a contributor edits a generated file directly.

The non-default Chinese filename README_ZH.md is preserved through
<\!--@nrg.fileNamePattern.zh=README_ZH.md-->.
@agmmnn

agmmnn commented Apr 28, 2026

Copy link
Copy Markdown
Owner

i’ve actually been thinking about doing something like this for a while

looks like the right direction for the repo. i’m a bit busy right now but i’ll take a closer look soon. thanks @andriishin 🙌

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.

2 participants