You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 1982b01
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+28Lines changed: 28 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,6 +43,7 @@ and is invoked through the `npm` scripts below, so you don't need to install any
43
43
|`npm run build`| Builds the library for publishing with `vp pack` (also runs attw and publint over the built output). |
44
44
|`npm run build:data`| Regenerates the datasets under `src/_internals/constants` from the IBGE/CONCLA sources (`scripts/data.ts`); run by the scheduled `Update datasets` workflow. |
45
45
|`npm run build:llms`| Regenerates `docs/llms.txt` and `docs/llms-full.txt` from the docs (`scripts/llms.ts`); CI fails if they're out of date. |
46
+
|`npm run build:site`| Regenerates the per-page copies of `docs/index.html`, `docs/404.html` and `docs/sitemap.xml` from the sidebars (`scripts/site.ts`); CI fails if they're out of date. |
46
47
|`npm run check:dependencies`| Fails if `package.json` declares any runtime `dependencies` (this package ships zero by design). |
47
48
|`npm run check:tree-shaking`| Builds nothing; measures the single-import size of every export against `dist` (`scripts/tree-shaking.ts`). Run it after `npm run build` when you change a dataset, and update the bundle-size table in `docs/getting-started.md` / `docs/pt-br/getting-started.md`. |
48
49
|`npm run check:duplication`| Runs [jscpd](https://jscpd.dev) over `src` and `scripts`; any copy-pasted block of 5+ lines / 50+ tokens fails. |
@@ -321,6 +322,33 @@ Every utility must keep working across all the runtimes this library targets:
321
322
Avoid Node-specific APIs unless they are polyfilled/guarded, and prefer standard, widely available
322
323
JavaScript/TypeScript features.
323
324
325
+
## Documentation site
326
+
327
+
`docs/` is the source of [brazilian-utils.com.br](https://brazilian-utils.com.br), served by GitHub
328
+
Pages with [docsify](https://docsify.js.org): `docs/index.html` renders the Markdown in the
329
+
browser, with `_sidebar.md`, `_navbar.md` and `_coverpage.md` as its navigation.
330
+
331
+
- docsify runs in history mode, so every page is a real URL (`/getting-started`,
332
+
`/pt-br/utilities`) that search engines index on its own. GitHub Pages serves each one from a
333
+
copy of `index.html` next to the page (`getting-started.html`) that carries the page's own
334
+
title, description, canonical URL and hreflang pair, and `npm run build:site`
335
+
(`scripts/site.ts`) writes those copies, `404.html` and `sitemap.xml` from the sidebars and the
336
+
pages' front matter. The Check workflow fails when they are stale, so run it after editing
337
+
`index.html`, a sidebar or a page's front matter. Links from the hash-router era
338
+
(`/#/getting-started?id=usage`) are rewritten on load, so nothing out there breaks.
339
+
- Every page starts with a front matter block with a quoted `title` and `description` (and
340
+
`keywords`), and has no `#` heading of its own: the plugin in `docs/index.html` turns the title
341
+
into the page's heading and the block feeds the page's metadata (a small wrapper there hands
342
+
the search plugin the same view, so the block never shows up in search results). Scripts read
343
+
the block through `scripts/front-matter.ts`.
344
+
-`scripts/llms.ts` reads the title back out of the front matter, so `docs/llms.txt` and
345
+
`docs/llms-full.txt` keep their headings; run `npm run build:llms` after editing a page.
346
+
- Context7 indexes `docs/` as `/brazilian-utils/javascript`; `context7.json` says what it reads,
347
+
and `.github/workflows/context7.yml` asks for a refresh when the docs change on `main`.
348
+
349
+
To preview the site, point a static file server that resolves `/page` to `page.html`, the way
350
+
GitHub Pages does, at `docs/`.
351
+
324
352
## Commit messages
325
353
326
354
This project follows [Conventional Commits](https://www.conventionalcommits.org/). Examples:
[](https://www.npmjs.com/package/@brazilian-utils/brazilian-utils)[](https://www.npmjs.com/package/@brazilian-utils/brazilian-utils)[](https://github.com/brazilian-utils/javascript/blob/main/LICENSE)
@@ -95,9 +95,10 @@ import { isValidCpf } from "@brazilian-utils/brazilian-utils";
95
95
isValidCpf("1232454233345"); // false
96
96
```
97
97
98
-
You can check a list of utilities [by clicking here](https://brazilian-utils.com.br/#/utilities).
98
+
You can check a list of utilities [by clicking here](https://brazilian-utils.com.br/utilities).
99
99
100
-
- The package is tree-shakeable. Every util is also available as its own subpath (e.g. `@brazilian-utils/brazilian-utils/get-cities`) so you can lazy-load the few heavy ones. See [Bundle size](https://brazilian-utils.com.br/#/getting-started?id=bundle-size).
100
+
- Using an AI coding assistant? The docs are indexed on Context7 as [`/brazilian-utils/javascript`](https://context7.com/brazilian-utils/javascript), and [llms.txt](https://brazilian-utils.com.br/llms.txt) lists every util for other tools. See [AI assistants](https://brazilian-utils.com.br/getting-started?id=ai-assistants).
101
+
- The package is tree-shakeable. Every util is also available as its own subpath (e.g. `@brazilian-utils/brazilian-utils/get-cities`) so you can lazy-load the few heavy ones. See [Bundle size](https://brazilian-utils.com.br/getting-started?id=bundle-size).
101
102
102
103
## Development
103
104
@@ -112,7 +113,7 @@ npm test
112
113
npm run build
113
114
```
114
115
115
-
[CONTRIBUTING.md](CONTRIBUTING.md) lists every script and the checks a pull request goes through.
116
+
[CONTRIBUTING.md](https://github.com/brazilian-utils/javascript/blob/main/CONTRIBUTING.md) lists every script and the checks a pull request goes through.
116
117
117
118
Release notes are published through [GitHub Releases](https://github.com/brazilian-utils/javascript/releases).
0 commit comments