Skip to content

docs: migrate 5 README files to a single NRG template#251

Open
andriishin wants to merge 1 commit into
voidcosmos:mainfrom
andriishin:nrg-migration
Open

docs: migrate 5 README files to a single NRG template#251
andriishin wants to merge 1 commit into
voidcosmos:mainfrom
andriishin:nrg-migration

Conversation

@andriishin
Copy link
Copy Markdown

Why

README.md, README.es.md, README.id.md, README.pt.md, README.tr.md are hand-maintained side-by-side. With 5 translations, every README change means editing the same paragraph in 5 places.

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

What changes

  • New: README.src.md — the unified source. Each line is tagged with <!--<lang>--> so it appears only in that language's output. Generated programmatically from the existing five files; 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 main touching README.src.md or workflow → regenerates and auto-commits.
    • PR touching any README*.md or template → drift check (mode: check) — fails with unified diff when a contributor edits a generated file directly.
  • Modified: all 5 README files — regenerated. The only change is the 2-line auto-generated header at the top.

Verification

Locally, regenerating with NRG 1.1 from Maven Central against current main (commit 72561db) produces output that diffs against the originals only by the 2-line auto-generated header. Zero functional content change.

What's intentionally NOT in this PR

  • Translation alignment. Today's content lives unchanged in README.src.md. Future PRs can extract shared structural elements (badges, demo gif, CLI option tables) into shared regions of the template.
  • Nothing in the npkill source/CLI/build is touched.

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 CLI, Maven plugin, GitHub Action, and library. Zero local toolchain needed when used through the action.

Replaces 5 hand-maintained READMEs (en + es/id/pt/tr) with a single
README.src.md, regenerated in CI by nanolaba/nrg-action@v1 on push
to main. All 5 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 any README*.md
or the template, failing the build with a unified diff when a
contributor edits a generated file directly.
@zaldih
Copy link
Copy Markdown
Member

zaldih commented May 16, 2026

Hello!

First of all, thank you so much for the effort and time you put into preparing this PR. It addresses exactly the problem I’ve been seeing for a while now, which is that maintaining so many languages is a huge issue in the long run. Especially in projects that are constantly changing. So your proposal hits the nail on the head in a smart way.

However, this PR arrives right as we are preparing the launch of npkill v1.0, which includes a radical overhaul of the tool and its docmuentation. Coinciding with this major milestone, I’ve decided that we are going to keep only English as the official language and acrhive the others. This is because translations quickly become outdated and end up confusing users more than helping them, so we want to simplify the project's maintenance moving forward.

Once again, thank you very much for this PR, because I think it’s very high quality (I wasn’t ear about Nanolaba, but I’ve been looking into it and it looks promising), but for the reasons mentioned above, I’ll be closing this PR.

Best regards,
Zaldih

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