BR Utils documentation site

This repository is the Docusaurus site for the BR Utils initiative: format, generate, and validate Brazilian CPF and CNPJ identifiers across programming languages.

Live site: https://br-utils.vercel.app

Requires Node.js >= 22 and Bun.

bun install
bun run dev      # sync READMEs, then start the local server
bun run build    # sync READMEs, then production build
bun run serve    # preview the production build

Each supported language is its own @docusaurus/plugin-content-docs instance (docs-js, docs-php, docs-python, docs-ruby). Java, Go, and Rust appear on the homepage as “coming soon” and do not have a docs instance yet.

• Default locale: pt-BR at / (no prefix). English is /en/.

• Do not use /pt or /pt-BR — those aliases redirect to the unprefixed path.

• English translations live in i18n/en/.

• docusaurus start serves one locale at a time. Use bun run dev for Portuguese and bun run dev:en for English (http://localhost:3000/en/). To try the navbar locale switch, use bun run build && bun run serve.

• English Getting Started pages live under:

  i18n/en/docusaurus-plugin-content-docs-<pluginId>/current/

Docs Getting Started pages are generated from each language repo’s root README. Do not edit the generated markdown by hand — change the README in br-utils-js (etc.) instead.

bun run sync

This also runs automatically as predev and prebuild.

Read order: local sibling folder first (../js/README.md, ../php, ../python, ../ruby), then GitHub raw content (https://raw.githubusercontent.com/LacusSolutions/<repo>/main/...) when the sibling clone is missing (CI / Vercel).

The shared transform (scripts/transform-readme.mjs):

• strips the cover image, CI/license badge rows, and “read in the other language” blockquotes
• rewrites remaining relative links/images to GitHub blob/raw URLs
• injects Docusaurus front matter (id: getting-started, slug: / so the page is /docs/<lang>)
• adds an MDX comment ({/* AUTO-GENERATED ... */}) rather than an HTML <!-- --> comment, which MDX rejects

Shared pipeline: scripts/transform-readme.mjs. Orchestration: scripts/sync-readmes.mjs.

Each language versions independently. Do not run this until you are ready to freeze a snapshot:

bunx docusaurus docs:version:docs-js 1.2.0
bunx docusaurus docs:version:docs-php 1.2.0
bunx docusaurus docs:version:docs-python 1.2.0
bunx docusaurus docs:version:docs-ruby 1.2.0

That creates <pluginId>_versions.json, <pluginId>_versioned_docs/, and <pluginId>_versioned_sidebars/ at the site root. The navbar version dropdown stays hidden until a language has more than one version.

MIT. See LICENSE.