diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d178c695..23444fa36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -387,9 +387,11 @@ browser, with `_sidebar.md`, `_navbar.md` and `_coverpage.md` as its navigation. the files to compile in its query string and `run.js` compiles them in the browser. The demos take their look from `docs/snippets/styles.css`. - The examples of the document field page are generated: `npm run build:examples` - (`scripts/examples.ts`) fills the templates of `docs/snippets/document-field/_templates` from a + (`scripts/examples.ts`) fills the templates of `docs/snippets/document-field/templates` from a table of documents, so the shared mask is written once. Edit a template or the table: the files - under `generated/` are written by the build and are not in the repository. + under `generated/` are written by the build and are not in the repository. A template ends in + `.tmpl` (`schema/zod.ts.tmpl`) because its `@@placeholder@@` markers do not parse as the language + its name says: the suffix keeps it out of everything that walks the repository for source files. - `scripts/llms.ts` reads the title back out of the front matter, so `docs/llms.txt` and `docs/llms-full.txt` keep their headings. - Context7 indexes `docs/` as `/brazilian-utils/javascript`; `context7.json` says what it reads, diff --git a/context7.json b/context7.json index 252f42c76..919ebd833 100644 --- a/context7.json +++ b/context7.json @@ -5,7 +5,7 @@ "projectTitle": "Brazilian Utils", "description": "Zero-dependency, tree-shakeable utilities for Brazilian data: validate, format, parse and generate CPF, CNPJ, CEP, boleto, Pix, holidays and more.", "folders": ["docs"], - "excludeFolders": ["docs/pt-br"], + "excludeFolders": ["docs/pt-br", "docs/snippets/document-field/templates"], "excludeFiles": [ "CHANGELOG.md", "CODE_OF_CONDUCT.md", diff --git a/docs/snippets/document-field/_templates/angular/document-field.ts b/docs/snippets/document-field/templates/angular/document-field.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/angular/document-field.ts rename to docs/snippets/document-field/templates/angular/document-field.ts.tmpl diff --git a/docs/snippets/document-field/_templates/angular/field.ts b/docs/snippets/document-field/templates/angular/field.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/angular/field.ts rename to docs/snippets/document-field/templates/angular/field.ts.tmpl diff --git a/docs/snippets/document-field/_templates/angular/form.ts b/docs/snippets/document-field/templates/angular/form.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/angular/form.ts rename to docs/snippets/document-field/templates/angular/form.ts.tmpl diff --git a/docs/snippets/document-field/_templates/angular/mask.ts b/docs/snippets/document-field/templates/angular/mask.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/angular/mask.ts rename to docs/snippets/document-field/templates/angular/mask.ts.tmpl diff --git a/docs/snippets/document-field/_templates/mask-body.ts b/docs/snippets/document-field/templates/mask-body.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/mask-body.ts rename to docs/snippets/document-field/templates/mask-body.ts.tmpl diff --git a/docs/snippets/document-field/_templates/react/document-field.tsx b/docs/snippets/document-field/templates/react/document-field.tsx.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/react/document-field.tsx rename to docs/snippets/document-field/templates/react/document-field.tsx.tmpl diff --git a/docs/snippets/document-field/_templates/react/field.tsx b/docs/snippets/document-field/templates/react/field.tsx.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/react/field.tsx rename to docs/snippets/document-field/templates/react/field.tsx.tmpl diff --git a/docs/snippets/document-field/_templates/react/form.tsx b/docs/snippets/document-field/templates/react/form.tsx.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/react/form.tsx rename to docs/snippets/document-field/templates/react/form.tsx.tmpl diff --git a/docs/snippets/document-field/_templates/react/mask.ts b/docs/snippets/document-field/templates/react/mask.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/react/mask.ts rename to docs/snippets/document-field/templates/react/mask.ts.tmpl diff --git a/docs/snippets/document-field/_templates/schema/arktype.ts b/docs/snippets/document-field/templates/schema/arktype.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/schema/arktype.ts rename to docs/snippets/document-field/templates/schema/arktype.ts.tmpl diff --git a/docs/snippets/document-field/_templates/schema/standard.ts b/docs/snippets/document-field/templates/schema/standard.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/schema/standard.ts rename to docs/snippets/document-field/templates/schema/standard.ts.tmpl diff --git a/docs/snippets/document-field/_templates/schema/valibot.ts b/docs/snippets/document-field/templates/schema/valibot.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/schema/valibot.ts rename to docs/snippets/document-field/templates/schema/valibot.ts.tmpl diff --git a/docs/snippets/document-field/_templates/schema/zod.ts b/docs/snippets/document-field/templates/schema/zod.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/schema/zod.ts rename to docs/snippets/document-field/templates/schema/zod.ts.tmpl diff --git a/docs/snippets/document-field/_templates/vanilla/field.html b/docs/snippets/document-field/templates/vanilla/field.html.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/vanilla/field.html rename to docs/snippets/document-field/templates/vanilla/field.html.tmpl diff --git a/docs/snippets/document-field/_templates/vue/document-field.vue b/docs/snippets/document-field/templates/vue/document-field.vue.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/vue/document-field.vue rename to docs/snippets/document-field/templates/vue/document-field.vue.tmpl diff --git a/docs/snippets/document-field/_templates/vue/field.vue b/docs/snippets/document-field/templates/vue/field.vue.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/vue/field.vue rename to docs/snippets/document-field/templates/vue/field.vue.tmpl diff --git a/docs/snippets/document-field/_templates/vue/form.vue b/docs/snippets/document-field/templates/vue/form.vue.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/vue/form.vue rename to docs/snippets/document-field/templates/vue/form.vue.tmpl diff --git a/docs/snippets/document-field/_templates/vue/mask.ts b/docs/snippets/document-field/templates/vue/mask.ts.tmpl similarity index 100% rename from docs/snippets/document-field/_templates/vue/mask.ts rename to docs/snippets/document-field/templates/vue/mask.ts.tmpl diff --git a/scripts/examples.ts b/scripts/examples.ts index b56568e44..2cdbb56b9 100644 --- a/scripts/examples.ts +++ b/scripts/examples.ts @@ -4,7 +4,7 @@ * Writes the examples the document field guide shows (`docs/guides/document-field.md`): one * focused example per document and framework, so a reader copies the CPF field, not a generic one * that has to be narrowed down first. Every file comes from a template in - * `docs/snippets/document-field/_templates`, filled in from the table below, together with the + * `docs/snippets/document-field/templates`, filled in from the table below, together with the * `mask` function they share. One page runs them all in the browser, `docs/snippets/live`, told * which files to compile by its query string. The Check workflow fails when these are stale. * @@ -17,7 +17,7 @@ import { join } from "node:path"; const ROOT = join(import.meta.dirname, ".."); const EXAMPLE_DIR = join(ROOT, "docs", "snippets", "document-field"); -const TEMPLATE_DIR = join(EXAMPLE_DIR, "_templates"); +const TEMPLATE_DIR = join(EXAMPLE_DIR, "templates"); type Document = { /** The kebab-case name of the document, which names its folder and its files. */ @@ -184,11 +184,15 @@ function values(document: Document): Record { } /** - * @param {string} name - A file of `docs/snippets/document-field/_templates`. + * A template carries `@@placeholder@@` markers, so it is not the language its name says it is: + * `schema/zod.ts` on its own does not parse as TypeScript. The extra `.tmpl` at the end keeps it + * out of every tool that walks the repository for `.ts`/`.tsx` files, the declaration build of the + * package included, while the extension before it still says what the filled in file will be. + * @param {string} name - A file of `docs/snippets/document-field/templates`, without the `.tmpl`. * @returns {string} Its contents. */ function readTemplate(name: string): string { - return readFileSync(join(TEMPLATE_DIR, name), "utf8"); + return readFileSync(join(TEMPLATE_DIR, `${name}.tmpl`), "utf8"); } /** diff --git a/tsconfig.json b/tsconfig.json index dba30ea21..01499eb0a 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -19,7 +19,9 @@ "noImplicitOverride": true }, // The documentation site is not part of the library: its examples are written for React, - // Angular and Vue, and the templates they are generated from are not valid TypeScript on their - // own. `npm run build:docs` and the type-check of each example live in the docs workflow. - "exclude": ["docs", "dist", "coverage", "reports", ".stryker-tmp"] + // Angular and Vue. `npm run build:docs` and the type-check of each example live in the docs + // workflow. `base` is the second checkout the Tree-shaking job of the build workflow writes + // there, a whole copy of the repository at the base revision of the pull request: the build + // running here compiles the head, never it. + "exclude": ["base", "docs", "dist", "coverage", "reports", ".stryker-tmp"] }