README

A local-first system that turns your folder of plain-text Markdown notes into a fast, interactive web app right on your computer. You write and tag your content directly inside your own Markdown files, and the app lets you browse, search, and explore them instantly in your browser. Because it is designed to run directly as a live deployment—pre-configured with Cloudflare adapters—your local workspace functions immediately as your live site without any extra build steps or complex databases.

Files

• emit.mjs: Reconciles deployment templates with target directories by preserving user configurations in files like wrangler.toml while propagating structural adapter updates.
• gen.mjs: Scans source markdown cards to ensure every item possesses a stable UUID v7 identifier and compiles them into an auto-generated JavaScript manifest module.
• 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.

Details

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

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

• 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

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.
3. ID Reconciliation: Iterates through each file to read and validate its ID token against the ID_RE pattern. Minting or collision handling writes updates back to disk immediately if modifications occur.
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 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

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

import { handler } from "./serve.mjs";
// Called within an edge worker / serverless fetch event handler
return handler(CARDS, TAGS, TITLE);

• CARDS: The compiled array of card objects, serialized and injected into the global scope.
• 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

• 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

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 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

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

• 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

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}}).
3. Adapter Projection: Iterates over all files in the plugin directory, maps special names (such as converting gitignore to .gitignore), injects the preserved configuration values, and writes them out to the target directory. Ensures the content/ directory structure exists without altering its contents.
4. Manifest Compilation: Executes gen.mjs within the context of the target directory to rebuild _manifest.js from the authored content.
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.