formatting and appendix
This commit is contained in:
@@ -5,11 +5,13 @@
|
||||
* **`serve.js`**: Edge runtime request handler that safely injects compiled card collections, tag vocabularies, and page titles into an HTML template for client hydration.
|
||||
* **`app.html`**: Single-page application shell and runtime that provides the UI styles, layout grid, and zero-dependency JavaScript parser to render cards and tag clouds in the browser.
|
||||
|
||||
# gen.mjs
|
||||
# Files
|
||||
|
||||
## gen.mjs
|
||||
|
||||
`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 <dir>] [--target <file>]
|
||||
@@ -18,13 +20,13 @@ node engine/gen.mjs [--src <dir>] [--target <file>]
|
||||
* **`--src <dir>`**: The source directory containing the markdown cards to process (defaults to `content`).
|
||||
* **`--target <file>`**: 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 (`<!-- id: <uuid> -->`). 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.
|
||||
@@ -32,15 +34,15 @@ node engine/gen.mjs [--src <dir>] [--target <file>]
|
||||
4. **Tag Parsing**: Extracts comma-delimited items from frontmatter `tags: [...]` declarations across all discovered markdown files to populate the global tag set.
|
||||
5. **Manifest Emission**: Generates static ES module imports for every markdown card, maps out metadata items (slug, id, imported content reference), serializes the sorted tag list, and writes the complete bundle to the target path.
|
||||
|
||||
# app.html
|
||||
## app.html
|
||||
|
||||
`app.html` is the single-page application shell and client-side runtime for the engine. It defines the layout, typography rules, CSS grid, and Web Animations API transitions, while embedding a zero-dependency JavaScript runtime to hydrate, parse, and render markdown cards and dynamic tag views directly in the browser.
|
||||
|
||||
# serve.js
|
||||
## serve.js
|
||||
|
||||
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";
|
||||
@@ -52,23 +54,23 @@ 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.
|
||||
3. **HTTP Response Dispatch**: Wraps the finalized HTML string in a `Response` instance with `text/html; charset=utf-8` headers ready for edge delivery.
|
||||
|
||||
# emit.mjs
|
||||
## emit.mjs
|
||||
|
||||
`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 <target> <dir>
|
||||
@@ -77,13 +79,13 @@ node engine/emit.mjs <target> <dir>
|
||||
* **`<target>`**: The deploy plugin directory located inside `engine/` (e.g., `cloudflare`).
|
||||
* **`<dir>`**: 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}}`).
|
||||
@@ -92,3 +94,9 @@ node engine/emit.mjs <target> <dir>
|
||||
5. **Scaffolding Notice**: Reports success and alerts the user if any required placeholder variables still need to be filled in prior to deployment.
|
||||
|
||||
|
||||
# Appendix
|
||||
|
||||
This project is released AND still in active development with new features on the way.
|
||||
|
||||
I hope you find it useful.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user