diff --git a/README.md b/README.md index 5d95666..b522705 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ `gen.mjs` is the manifest generator and identifier minting engine. It scans markdown files within a source directory, ensures every card possesses a stable UUID v7 identifier, and compiles an auto-generated JavaScript manifest module exposing the card collection and tag vocabulary. -### Usage +#### Usage ```bash node engine/gen.mjs [--src ] [--target ] @@ -20,13 +20,13 @@ node engine/gen.mjs [--src ] [--target ] * **`--src `**: The source directory containing the markdown cards to process (defaults to `content`). * **`--target `**: The output file path for the generated manifest module (defaults to `_manifest.js`). -### Core Principles +#### Core Principles * **UUID v7 Minting & Auditing**: Scans each `.md` file for an embedded HTML comment ID (``). If absent, it mints a new time-ordered UUID v7 and appends it to the bottom of the card. If a duplicate ID collision is detected across files, it automatically remints a fresh UUID in place. * **Metadata Extraction**: Parses YAML frontmatter blocks within the markdown cards to automatically extract and aggregate a unified, sorted tag vocabulary. * **Manifest Compilation**: Employs static relative module specifiers to build an indexed `CARDS` array and a `TAGS` vocabulary array, exporting them for build-time and boot-time consumption while strictly marking the output as auto-generated. -### Workflow Execution +#### Workflow Execution 1. **Argument Resolution**: Resolves command-line overrides for the source directory (`--src`) and target output (`--target`), falling back to default values. 2. **File Discovery**: Filters the source directory for all files ending in `.md` and sorts them alphabetically. @@ -42,7 +42,7 @@ node engine/gen.mjs [--src ] [--target ] This module acts as the edge runtime request handler, injecting application data and metadata into an HTML shell to serve the client-side application. -### Usage +#### Usage ```javascript import { handler } from "./serve.mjs"; @@ -54,13 +54,13 @@ return handler(CARDS, TAGS, TITLE); * **`TAGS`**: The sorted array of tag vocabulary strings, serialized and injected alongside cards. * **`TITLE`**: The site or page title string injected into the HTML title placeholder. -### Core Principles +#### Core Principles * **Data Injection**: Serializes the `CARDS` collection and `TAGS` vocabulary into JavaScript assignment statements (`window.__CARDS__` and `window.__TAGS__`) to hydrate the client-side environment on load. * **Safe String Replacement**: Utilizes functional replacement patterns (`() => ...`) within string replacement methods to prevent unintended `$` pattern or special character interpretation. * **Response Generation**: Constructs and returns a standard HTTP `Response` object containing the fully assembled HTML payload with the proper UTF-8 content-type header. -### Workflow Execution +#### Workflow Execution 1. **Payload Construction**: Generates global window assignment strings containing the JSON stringified representations of the card collection and tag vocabulary. 2. **Template Hydration**: Imports the raw HTML template (`app.html`), safely replacing the `__TITLE__` token with the provided title value and the `/*__DATA__*/` comment placeholder with the injected data script. @@ -70,7 +70,7 @@ return handler(CARDS, TAGS, TITLE); `emit.mjs` is the deployment adapter projection engine. It reconciles engine-level deployment templates with target-specific instance directories, preserving user configuration while propagating structural template updates. -### Usage +#### Usage ```bash node engine/emit.mjs @@ -79,13 +79,13 @@ node engine/emit.mjs * **``**: The deploy plugin directory located inside `engine/` (e.g., `cloudflare`). * **``**: The target instance directory where the adapter files will be projected. -### Core Principles +#### Core Principles * **Rebuild & Preserve**: Reads per-target configuration values (such as `name` and `TITLE`) out of existing target files (`wrangler.toml`), then regenerates all adapter files from the plugin templates carrying those values. Structural template changes automatically propagate on every run. * **Authored Content Protection**: The `content/` directory is authored data—it is never generated, overwritten, or touched by the emitter. * **Manifest Generation**: Automatically invokes the engine's `gen.mjs` script against the target's `content/` directory to build the `_manifest.js` index. -### Workflow Execution +#### Workflow Execution 1. **Validation**: Verifies that both arguments are provided and that the specified deploy plugin exists under the engine path. 2. **Configuration Extraction**: Scans the existing target configuration (`wrangler.toml`) for pre-existing custom tokens like `NAME` and `TITLE`. If absent, defaults to template placeholders (`{{NAME}}`, `{{TITLE}}`).