@beforesemicolon/builder 1.8.11 → 1.8.18

package/README.md

@@ -1,219 +1,916 @@
 # @beforesemicolon/builder
 
-Utilities to build npm packages and a documentation website for Before Semicolon projects.
+Utilities to build npm packages and static documentation websites for Before Semicolon projects.
 
-This package provides small, focused helpers to:
+This package provides three public helpers:
 
-- Build server-friendly CommonJS and ESM module bundles (dist/cjs and dist/esm).
-- Produce a browser bundle (dist/client.js) for documentation or demos.
-- Render a static documentation website from Markdown files (output defaults to `website/`).
+- `buildModules()` builds TypeScript sources into `dist/esm` and `dist/cjs`.
+- `buildBrowser()` builds a browser bundle, usually for demos or docs.
+- `buildDocs()` renders a static Markdown documentation site.
 
-Table of contents
+The docs builder supports reusable templates, Markdown layout blocks, source-level template extension, generated SEO/AI files, theme variables, page scripts, assets, stylesheets, and custom `marked` options.
 
-- Features
-- Requirements
-- Installation
-- Quick examples
-    - Library usage (Node)
-    - Building the browser bundle
-    - Generating the documentation website
-- API
-    - buildModules(options?)
-    - buildBrowser(options?)
-    - buildDocs(options?)
-- Documentation site layout and front-matter
-- Scripts (in package.json)
-- Development
-- Contributing
-- License
+## Requirements
 
-Features
+- Node.js `>=18.16.0`
+- ESM projects are supported directly.
+- CommonJS consumers can use the package `require` export.
 
-- Builds all TypeScript sources into both ESM and CJS formats using esbuild.
-- Produces a single browser bundle for client-side documentation UI.
-- Static site generator for Markdown: supports layouts, assets, stylesheets, and scripts.
-- Uses marked + highlight.js for Markdown rendering, DOMPurify for sanitization and minifies output CSS/JS/HTML.
-- Simple, zero-config defaults plus options for common customization.
+## Installation
 
-Requirements
+```sh
+npm install --save-dev @beforesemicolon/builder
+```
+
+## Quick Start
+
+```js
+import { buildModules, buildBrowser, buildDocs } from '@beforesemicolon/builder'
 
-- Node.js >= 18.16.0 (see `engines` in package.json)
+await buildModules()
+await buildBrowser()
+await buildDocs()
+```
 
-Installation
+Common project script:
 
-Install from npm (package name: `@beforesemicolon/builder`) or use the repo directly.
+```js
+import { buildModules, buildBrowser, buildDocs } from '@beforesemicolon/builder'
 
+const docsOptions = {
+    template: 'fading-citrus',
+    siteUrl: 'https://example.com',
+    generatedFiles: {
+        netlify: true,
+    },
+}
+
+const run = async () => {
+    await Promise.all([buildModules(), buildBrowser(), buildDocs(docsOptions)])
+}
+
+run()
 ```
-# npm
-npm install @beforesemicolon/builder
 
-# or using the repository
-git clone https://github.com/beforesemicolon/builder.git
-cd builder
-npm install
+## API
+
+### buildModules(options?)
+
+```ts
+buildModules(options?: {
+    directoryPath?: string
+}): Promise<void>
+```
+
+Builds source files into server-friendly ESM and CommonJS output.
+
+Defaults:
+
+- `directoryPath`: `process.cwd()/src`
+- ESM output: `dist/esm`
+- CommonJS output: `dist/cjs`
+
+Behavior:
+
+- Recursively scans the source directory.
+- Skips files ending in `.spec.ts`.
+- Skips `/client.ts` from module builds.
+- Uses `esbuild`.
+- Minifies output.
+- Keeps symbol names for better stack traces.
+
+### buildBrowser(options?)
+
+```ts
+buildBrowser(options?: {
+    entry?: string
+    out?: string
+}): Promise<void>
 ```
 
-Quick examples
+Builds a single browser bundle.
 
-Library usage (Node / programmatic)
+Defaults:
+
+- `entry`: `src/client`
+- `out`: `dist/client.js`
+
+Behavior:
+
+- Uses `esbuild`.
+- Generates sourcemaps.
+- Minifies output.
+- Includes a small internal plugin that removes the `Doc` export from `@beforesemicolon/html-parser` when bundling.
+
+### buildDocs(options?)
+
+```ts
+buildDocs(options?: {
+    srcDir?: string
+    publicDir?: string
+    markedOptions?: MarkedExtension
+    template?: string
+    siteUrl?: string
+    generatedFiles?:
+        | boolean
+        | {
+              sitemap?: boolean
+              robots?: boolean
+              llms?: boolean
+              llmsFull?: boolean
+              netlify?: boolean
+          }
+}): Promise<void>
+```
+
+Builds a static documentation site from Markdown.
+
+Defaults:
+
+- `srcDir`: `process.cwd()/docs`
+- `publicDir`: `process.cwd()/website`
+- `template`: no named template, uses the built-in `default` layout
+- `generatedFiles`: enabled for `sitemap`, `robots`, `llms`, and `llmsFull`
+- `generatedFiles.netlify`: `false`
+
+Example:
 
 ```js
-// ESM
-import { buildModules, buildBrowser, buildDocs } from '@beforesemicolon/builder'
+await buildDocs({
+    template: 'fading-citrus',
+    siteUrl: 'https://docs.example.com',
+    generatedFiles: {
+        netlify: true,
+    },
+})
+```
+
+## Docs Directory Structure
+
+The default source directory is `docs/`.
+
+```txt
+docs/
+  index.md
+  guide/
+    getting-started.md
+  assets/
+  stylesheets/
+  scripts/
+  _layouts/
+  _template/
+    template.config.js
+    assets/
+    stylesheets/
+    scripts/
+    layouts/
+  robots.txt
+  sitemap.xml
+  llms.txt
+  llms-full.txt
+  _redirects
+  netlify.toml
+```
 
-// Build server-side modules (dist/esm and dist/cjs)
-await buildModules({ directoryPath: 'src' })
+Supported folders:
 
-// Build single browser bundle (defaults to src/client -> dist/client.js)
-await buildBrowser({ entry: 'src/client', out: 'dist/client.js' })
+- `assets/`: copied to the same relative location in the output directory.
+- `stylesheets/`: CSS files are minified and copied to output.
+- `scripts/`: JS files are minified and copied to output.
+- `_layouts/`: page layout modules. Each file default-exports a page layout function.
+- `_template/`: source-level extension for the selected template.
+- `_template/assets/`: copied into `publicDir/assets`, overriding or extending template assets.
+- `_template/stylesheets/`: copied into `publicDir/stylesheets`, overriding or extending template styles.
+- `_template/scripts/`: copied into `publicDir/scripts`, overriding or extending template scripts.
+- `_template/layouts/`: custom page layouts that can override or extend selected template layouts.
+- `_template/template.config.js`: source-level template config merged with the selected template config.
 
-// Generate static docs (defaults: docs -> website)
-await buildDocs({ srcDir: 'docs', publicDir: 'website' })
+Files and folders starting with `.` or `_` are skipped during Markdown page discovery. `_template` and `_layouts` are used explicitly by the docs builder.
+
+## Page Front Matter
+
+Each Markdown page can include front matter:
+
+```md
+---
+name: Get Started
+title: Get Started with Example
+description: Learn how to install and use Example.
+order: 1
+layout: document
+---
+
+# Get Started
 ```
 
-CommonJS
+Common fields:
+
+- `name`: label used in the generated site map.
+- `title`: HTML title and generated metadata title.
+- `description`: meta description and generated metadata description.
+- `order`: numeric sort order for site map and generated files.
+- `layout`: page layout name. Defaults to `default`.
+
+The final page props include:
+
+```ts
+interface PageProps {
+    name?: string
+    path?: string
+    order?: number
+    title?: string
+    description?: string
+    content?: string
+    siteMap?: SiteMap
+    tableOfContent?: Array<{
+        path: string
+        label: string
+        level: string
+    }>
+    projectMeta?: {
+        name: string
+        version: string
+        [key: string]: unknown
+    }
+    renderMarkdown?: (markdown: string) => string
+    scripts?: string[]
+    themeStylesheet?: string
+}
+```
+
+## Page Layouts
+
+Page layouts render complete HTML documents. A layout file must default-export a function that receives `PageProps` and returns an HTML string.
+
+Example `docs/_layouts/document.js`:
 
 ```js
-const {
-    buildModules,
-    buildBrowser,
-    buildDocs,
-} = require('@beforesemicolon/builder')
+export default ({
+    title,
+    description,
+    content,
+    scripts = [],
+}) => `<!doctype html>
+<html>
+    <head>
+        <meta charset="utf-8">
+        <meta name="description" content="${description || ''}">
+        <title>${title || ''}</title>
+    </head>
+    <body>
+        ${content || ''}
+        ${scripts.join('')}
+    </body>
+</html>`
+```
+
+Layout lookup order:
+
+1. Built-in layouts.
+2. Selected template layouts.
+3. `docs/_layouts`.
+4. `docs/_template/layouts`.
+
+Later layout files with the same basename override earlier ones.
 
-;(async () => {
-    await buildModules()
-    await buildBrowser()
-    await buildDocs()
-})()
+## Templates
+
+Named templates are loaded from:
+
+```txt
+src/docs/templates/<template-name>/
 ```
 
-CLI / npm scripts
+Available templates:
+
+- `fading-citrus`: a complete landing and documentation template with Markdown layout handlers, theme variables, assets, and page scripts. See [fading-citrus template README](./src/docs/templates/fading-citrus/README.md).
 
-The repo ships with a `build` script that will emit types and run the TypeScript build entry (`build.ts`).
+A template can provide:
 
+```txt
+template.config.js
+assets/
+stylesheets/
+scripts/
+layouts/
 ```
-npm run build
+
+The selected template is a complete out-of-the-box docs site shell. A docs source can extend it through `docs/_template`. Template-specific layouts, assets, options, and assumptions should be documented by each template.
+
+## Template Config
+
+A template config exports an object:
+
+```js
+export default {
+    markedOptions: {},
+    markdownLayouts: {},
+    scripts: {},
+    theme: {
+        light: {},
+        dark: {},
+    },
+}
+```
+
+Config from `docs/_template/template.config.js` is merged into the selected template config.
+
+Merge behavior:
+
+- `markdownLayouts` are shallow-merged by layout name.
+- `scripts` are shallow-merged by script name.
+- `theme.light` and `theme.dark` are shallow-merged by CSS variable name.
+- Other top-level config values use the docs source config value when provided.
+
+Example docs source extension:
+
+```js
+import pricingCards from './layouts/pricing-cards.js'
+
+export default {
+    markdownLayouts: {
+        'pricing-cards': pricingCards,
+    },
+    theme: {
+        light: {
+            '--primary': 'oklch(0.62 0.18 250)',
+        },
+        dark: {
+            '--primary': 'oklch(0.76 0.16 250)',
+        },
+    },
+}
+```
+
+## Markdown Layout Syntax
+
+The docs renderer extends `marked` with a custom block syntax:
+
+```md
+::: layout <type> [options]
+
+=== <name> [options]
+
+Markdown content for this part.
+
+=== <name> [options]
+
+More Markdown content.
+
+:::
+```
+
+Example:
+
+```md
+::: layout grid columns=3 gap=lg
+
+=== card span=2
+
+## First card
+
+Markdown content.
+
+=== card sticky
+
+## Second card
+
+More Markdown content.
+
+===
+
+Unnamed item.
+
+:::
 ```
 
-This runs TypeScript declaration emission and then executes `build.ts` which calls `buildModules()` to produce the `dist/` outputs.
+Header parsing:
 
-API
+```txt
+::: layout grid columns=3 gap=lg
+```
 
-- buildModules(options?: { directoryPath?: string }) => Promise
-    - Scans the given directory (default: `process.cwd()/src`) recursively for files and builds them into:
-        - `dist/esm` (ESM format)
-        - `dist/cjs` (CommonJS format)
-    - Files ending with `.spec.ts` or `/client.ts` are ignored from the module build set.
-    - Uses `esbuild` with minification and keeps symbol names for better stack traces.
+Produces:
 
-- buildBrowser(options?: { entry?: string; out?: string }) => Promise
-    - Bundles a single browser file using `esbuild`.
-    - Defaults: `entry` -> `src/client`, `out` -> `dist/client.js`.
-    - Includes a small plugin to remove the `Doc` export from `@beforesemicolon/html-parser` during bundling (keeps bundle size smaller when that export isn't used).
-    - Generates sourcemaps and minifies the output.
+```js
+{
+    type: 'grid',
+    options: {
+        columns: 3,
+        gap: 'lg',
+    },
+}
+```
 
-- buildDocs(options?: { srcDir?: string; publicDir?: string }) => Promise
-    - Generates a static documentation website from a Markdown `docs` directory.
-    - Defaults: `srcDir` -> `docs`, `publicDir` -> `website`.
-    - Supported docs structure (defaults used by the generator):
-        - `_layouts/` — custom templates (each module should default-export a function matching `PageProps`)
-        - `assets/` — copied to the site output
-        - `stylesheets/` — CSS files are minified and copied
-        - `scripts/` — JS files are minified and copied
-        - `*.md` — Markdown pages with front-matter to control metadata
-    - Pages use `marked` with a custom renderer (heading IDs, code blocks, links) and `highlight.js` for syntax highlighting.
-    - HTML is sanitized with DOMPurify and minified with `html-minifier`.
+Item header parsing:
 
-Documentation site layout and front-matter
+```txt
+=== hero span=2 sticky
+```
+
+Produces:
 
-Markdown pages should contain front-matter (YAML) with properties compatible with the site's `PageProps`:
+```js
+{
+    name: 'hero',
+    options: {
+        span: 2,
+        sticky: true,
+    },
+}
+```
 
-- title: string — page title (used in the HTML title)
-- description: string — meta description
-- order: number — numeric order used when building the site map and sorting pages
-- layout: string — layout name; corresponds to a template in `_layouts` (default: `default`)
+Unnamed items are supported:
+
+```md
+===
+
+Content
+```
 
-PageProps (shape used by layouts)
+Produces:
 
-- name: string
-- path: string (page path, e.g. `/guide/getting-started.html`)
-- order: number
-- title: string
-- description: string
-- content: string (HTML produced from Markdown)
-- siteMap: Map representing the site structure
-- tableOfContent: array of { path, label } entries generated from headings
+```js
+{
+    name: null,
+    options: {},
+}
+```
+
+Option parsing rules:
+
+- `key=value` becomes a keyed option.
+- Bare words become boolean `true`.
+- Numeric values become numbers.
+- `true` and `false` become booleans.
+- Quoted values are supported.
+
+Examples:
+
+```txt
+columns=3
+gap=lg
+sticky
+label="Get Started"
+enabled=false
+```
+
+Nested layout blocks are supported. Nested blocks are preserved inside the parent item body and rendered through the same Markdown renderer.
+
+## Markdown Layout Handlers
+
+Markdown layout handlers are registered through `template.config.js`:
+
+```js
+import pricingCards from './layouts/pricing-cards.js'
+
+export default {
+    markdownLayouts: {
+        'pricing-cards': pricingCards,
+    },
+}
+```
 
-A minimal docs layout example (the package ships a simple `default` template):
+A handler receives parsed layout data and a rendering context:
 
 ```ts
-export default ({ title, description, content }) => `
+type MarkdownLayoutHandler = (
+    layout: {
+        type: string
+        options: Record<string, string | number | boolean>
+        parts: Array<{
+            name: string | null
+            options: Record<string, string | number | boolean>
+            body: string
+            html: string
+        }>
+        raw: string
+    },
+    context: {
+        renderMarkdown(markdown: string): string
+        renderDefault(node): string
+        renderParts(node): Array<{ html: string }>
+    }
+) => string
+```
+
+Each part body is rendered from Markdown to HTML before the handler receives it. Use `part.html` when injecting content.
+
+Example handler:
+
+```js
+export default ({ parts, options }) => {
+    const tierClass = options.featured ? ' pricing-cards-featured' : ''
+
+    return `<div class="pricing-cards${tierClass}">
+        ${parts
+            .map(
+                (
+                    part,
+                    index
+                ) => `<section class="pricing-card option-${index + 1}">
+                    ${part.html}
+                </section>`
+            )
+            .join('')}
+    </div>`
+}
+```
+
+Markdown:
+
+```md
+::: layout pricing-cards featured
+
+===
+
+## Starter
+
+$10/month
+
+===
+
+## Pro
+
+$30/month
+
+:::
+```
+
+Generated HTML is entirely controlled by the handler.
+
+## Default Markdown Layout Rendering
+
+If a layout type has no custom handler, builder renders a generic structure:
+
+```html
+<div
+    class="bfs-layout bfs-layout-grid"
+    data-layout="grid"
+    style="--columns: 3; --gap: lg;"
+>
+    <section class="bfs-layout-item" data-name="card" style="--span: 2;">
+        ...
+    </section>
+</div>
+```
+
+Boolean options are omitted from inline styles. Non-boolean options are converted to CSS custom properties.
+
+## marked Options
+
+The docs builder uses `marked`, `marked-highlight`, and a custom renderer for headings, code, and links.
+
+You can extend `marked` globally for docs generation:
+
+```js
+await buildDocs({
+    markedOptions: {
+        renderer: {
+            codespan({ text }) {
+                return `<code data-inline>${text}</code>`
+            },
+        },
+    },
+})
+```
+
+Templates can also provide `markedOptions` through `template.config.js`.
+
+## Page Scripts
+
+Template scripts are declared in `template.config.js`.
+
+```js
+import { renderCodeCopyScript } from './layouts/_code-snippet.js'
+
+export default {
+    scripts: {
+        'code-copy': {
+            match: 'code-copy-btn',
+            render: renderCodeCopyScript,
+        },
+    },
+}
+```
+
+Script definitions:
+
+```ts
+type DocsScriptMatcher =
+    | string
+    | string[]
+    | RegExp
+    | ((html: string) => boolean)
+
+interface DocsScriptDefinition {
+    match?: DocsScriptMatcher
+    render: () => string
+}
+
+type DocsScriptRegistry = Record<
+    string,
+    false | DocsScriptDefinition | (() => string)
+>
+```
+
+Behavior:
+
+- Scripts are rendered per page after Markdown has been rendered.
+- If `match` is omitted, the script is included on every page.
+- A string matcher checks `html.includes(match)`.
+- An array matcher checks whether any string is present.
+- A RegExp matcher tests the rendered page HTML.
+- A function matcher receives the rendered page HTML and returns a boolean.
+- A script can be disabled by setting its registry value to `false` in an extending config.
+
+Layouts receive scripts through `props.scripts` and must insert them where appropriate, usually before `</body>`.
+
+```js
+export default (props) => `
 <!doctype html>
 <html>
-  <head>
-    <meta charset="utf-8" />
-    <meta name="description" content="${description}" />
-    <title>${title}</title>
-  </head>
-  <body>
-    ${content}
-  </body>
+    <body>
+        ${props.content}
+        ${props.scripts?.join('') || ''}
+    </body>
 </html>`
 ```
 
-Scripts (from package.json)
+## Theme Variables
 
-- `build` — removes `dist`, emits TypeScript declarations, then runs `build.ts` (which calls `buildModules`).
-- `lint` — runs ESLint and Prettier check
-- `format` — runs ESLint autofix and Prettier write
+Templates can define theme variables in `template.config.js`:
 
-Development
+```js
+export default {
+    theme: {
+        light: {
+            '--background': 'oklch(0.98 0.006 250)',
+            '--foreground': 'oklch(0.18 0.015 250)',
+            '--primary': 'oklch(0.66 0.18 45)',
+        },
+        dark: {
+            '--background': 'oklch(0.18 0.015 250)',
+            '--foreground': 'oklch(0.96 0.005 250)',
+            '--primary': 'oklch(0.74 0.18 45)',
+        },
+    },
+}
+```
 
-- Ensure you use Node >= 18.16.0
-- Install dependencies:
+Builder converts theme variables into:
 
+```txt
+website/stylesheets/theme.css
 ```
-npm install
+
+The generated file includes:
+
+- `:root` variables.
+- `@media (prefers-color-scheme: dark)` variables.
+- `[data-theme="light"]` variables.
+- `[data-theme="dark"]` variables.
+
+A theme mode can be disabled with `false`:
+
+```js
+export default {
+    theme: {
+        light: false,
+    },
+}
 ```
 
-- Run the build pipeline locally:
+When one mode is disabled, the remaining mode is emitted as `:root`. For example, `light: false` makes the dark theme the default theme and skips light-mode selectors and `prefers-color-scheme` switching.
 
+Page layouts receive:
+
+```ts
+themeStylesheet?: string
 ```
-npm run build
+
+Templates should include it in `<head>`:
+
+```js
+${props.themeStylesheet ? `<link rel="stylesheet" href="${props.themeStylesheet}">` : ''}
+```
+
+Docs sources can override only variable values by adding `docs/_template/template.config.js`.
+
+## Generated Files
+
+`buildDocs()` can generate common root-level files into `publicDir`.
+
+Defaults:
+
+```js
+generatedFiles: {
+    sitemap: true,
+    robots: true,
+    llms: true,
+    llmsFull: true,
+    netlify: false,
+}
 ```
 
-- Lint and format:
+Disable all generated files:
 
+```js
+await buildDocs({
+    generatedFiles: false,
+})
 ```
-npm run lint
-npm run format
+
+Enable Netlify files:
+
+```js
+await buildDocs({
+    siteUrl: 'https://docs.example.com',
+    generatedFiles: {
+        netlify: true,
+    },
+})
+```
+
+Generated files:
+
+- `sitemap.xml`: generated from discovered Markdown pages. Requires `siteUrl`.
+- `robots.txt`: generated with `Allow: /` and a sitemap URL when `siteUrl` is provided.
+- `llms.txt`: generated page index for AI tools.
+- `llms-full.txt`: generated expanded page index with source paths, descriptions, and summaries.
+- `_redirects`: generated only when `generatedFiles.netlify` is `true`.
+- `netlify.toml`: generated only when `generatedFiles.netlify` is `true`.
+
+Source-first behavior:
+
+- If `docs/sitemap.xml` exists, it is copied to `publicDir/sitemap.xml` instead of generated.
+- If `docs/robots.txt` exists, it is copied to `publicDir/robots.txt` instead of generated.
+- If `docs/llms.txt` exists, it is copied to `publicDir/llms.txt` instead of generated.
+- If `docs/llms-full.txt` exists, it is copied to `publicDir/llms-full.txt` instead of generated.
+- If `generatedFiles.netlify` is `true` and `docs/_redirects` exists, it is copied to `publicDir/_redirects` instead of generated.
+- If `generatedFiles.netlify` is `true` and `docs/netlify.toml` exists, it is copied to `publicDir/netlify.toml` instead of generated.
+
+Netlify notes:
+
+- `_redirects` is treated as Netlify-specific.
+- `netlify.toml` is written to `publicDir`, not the project root.
+- Generated `netlify.toml` defaults to `command = "node build-docs.js"` and `publish = "website"` unless `publicDir` has a different basename.
+
+## llms-full.txt Content
+
+The generated `llms-full.txt` is derived from discovered Markdown pages.
+
+For each page it uses:
+
+- `title`: front matter `title`, fallback to `name`, fallback to `Documentation`.
+- `description`: front matter `description`, fallback to stripped Markdown body text.
+- `URL`: file-derived page URL joined with `siteUrl`.
+- `Source`: relative Markdown source path.
+- `summary`: first 320 characters of stripped Markdown body text.
+
+The body summary is not the final rendered HTML. It is a lightweight Markdown text extraction used for AI-facing page discovery.
+
+## Extension Example
+
+Project docs:
+
+```txt
+docs/
+  index.md
+  _template/
+    template.config.js
+    assets/
+      logo.svg
+    layouts/
+      pricing-cards.js
+```
+
+`docs/_template/template.config.js`:
+
+```js
+import pricingCards from './layouts/pricing-cards.js'
+
+export default {
+    markdownLayouts: {
+        'pricing-cards': pricingCards,
+    },
+    scripts: {
+        analytics: {
+            match: '<main',
+            render: () => `<script>console.log('page viewed')</script>`,
+        },
+    },
+    theme: {
+        light: {
+            '--primary': 'oklch(0.62 0.18 250)',
+        },
+        dark: {
+            '--primary': 'oklch(0.78 0.16 250)',
+        },
+    },
+}
 ```
 
-- The source entry points are in `src/`. `src/build-modules.ts`, `src/build-browser.ts` and `src/docs/run.ts` provide the public functionality.
+`docs/index.md`:
+
+```md
+---
+title: Example
+description: Example documentation.
+layout: landing
+---
+
+::: layout pricing-cards featured
+
+===
+
+## Starter
+
+For small teams.
+
+===
+
+## Pro
 
-Testing and validation
+For growing teams.
+
+:::
+```
+
+## Build Output
+
+Given default options, output is written to:
+
+```txt
+website/
+  index.html
+  guide/
+    getting-started.html
+  assets/
+  stylesheets/
+  scripts/
+  robots.txt
+  sitemap.xml
+  llms.txt
+  llms-full.txt
+```
+
+If `generatedFiles.netlify` is `true`, output also includes:
+
+```txt
+website/
+  _redirects
+  netlify.toml
+```
 
-This repository does not include automated tests by default. If you add tests, consider using the existing devDependencies (TypeScript + ts-jest + tinybench if you want benchmarks).
+## Package Scripts
 
-Contributing
+This repo provides:
 
-Contributions are welcome. A good workflow is:
+- `npm run build`: removes `dist`, emits TypeScript declarations, then builds package outputs.
+- `npm run lint`: runs ESLint and Prettier checks.
+- `npm run format`: runs ESLint autofix and Prettier write.
+- `npm test`: runs the Markdown layout parser/renderer tests.
 
-1. Fork the repository and create a feature branch.
-2. Add or modify code in `src/`.
-3. Run `npm run build` to check the build output.
-4. Run `npm run lint` or `npm run format` to keep code style consistent.
-5. Open a pull request describing the change.
+## Development
 
-License
+Install dependencies:
+
+```sh
+npm install
+```
+
+Run checks:
+
+```sh
+npm run lint
+npm test
+npm run build
+```
+
+Pack locally:
+
+```sh
+npm pack
+```
+
+Install the packed artifact into a sibling project:
+
+```sh
+npm install ../builder/beforesemicolon-builder-<version>.tgz
+```
 
-BSD-3-Clause — see `package.json` for author and license metadata.
+## Implementation Notes
 
-Acknowledgements and internals
+- Markdown rendering uses `marked`.
+- Syntax highlighting uses `marked-highlight` and `highlight.js`.
+- Front matter parsing uses `front-matter`.
+- HTML is sanitized with `isomorphic-dompurify`.
+- HTML output is minified with `html-minifier`.
+- CSS output is minified with `clean-css`.
+- JS output copied from docs script folders is minified with `@putout/minify`.
+- Static module and browser builds use `esbuild`.
 
-- Uses `esbuild` for fast bundling and minification.
-- Markdown rendering powered by `marked` with a custom renderer and `marked-highlight` plugin using `highlight.js`.
-- Front-matter parsing via `front-matter`.
-- DOM sanitization by `isomorphic-dompurify` and HTML/CSS/JS minification using `html-minifier`, `clean-css`, and `@putout/minify` respectively.
+## License
 
-If you'd like any sections expanded (examples, advanced options, or a CONTRIBUTING.md), tell me which parts to elaborate and I'll add them.
+BSD-3-Clause. See `package.json`.