📂 Project Structure & Workflow

Mustela thrives on a "Zero-Constraint" philosophy. You are not forced into a specific directory structure; instead, you define your workspace via CLI arguments. Whether it’s a standalone blog or a complex Vite-powered application, Mustela adapts to your pipeline.

1. Workspace Blueprints

The Vanilla Blueprint (Standalone)

Designed for maximum simplicity and zero dependencies. The dist folder is your final product.

.
├── config/
│   └── mustela.mu        # Global site state & constants
├── content/              # Raw data (Markdown)
│   └── index.md
├── theme/                # Logic & Layouts
│   └── default/          # Active theme folder
│       └── main.mu       # Entry point block
└── dist/                 # Output directory (generated)
    └── public/           # Static assets (Directly served)

The Modern Workspace (Vite / Bun Preset)

For engineers who need Tailwind, PostCSS, and Hot Module Replacement. In this setup, Mustela acts as the "HTML Engine" within a larger frontend ecosystem.

.
├── config/               # Global state
├── content/              # Content source
├── theme/                # Template source
├── vite_dev/             # Asset source for the Bundler
│   └── public/           # Assets managed by Vite
├── package.json          # Pipeline dependencies
├── vite.config.js        # Asset orchestration
└── dist/                 # Final optimized bundle

2. CLI: The Control Center

You control the data flow. If a directory is moved, just tell the engine where to look.

3. The Lifecycle: From Markdown to Memory

Phase 1: Recursive Template Loading

Mustela doesn't just open a file; it ingests a folder. When you point to a theme (e.g., ./theme/default), the engine recursively loads every .mu file. This allows you to treat your theme like a component library (e.g., nav.mu, sidebar.mu, footer.mu). All blocks are pooled into a single, high-speed memory state.

Phase 2: The Matchmaking Logic

Mustela maps Markdown to HTML blocks based on a hierarchy:

• Explicit: If index: "custom" exists in Markdown metadata, look for html as custom do.
• Implicit: Fallback to html as main do.
• Safety Catch: If the specified block doesn't exist, Mustela won't crash. Instead, it produces an empty output for that specific page, ensuring the rest of the build completes without interruption.

Phase 3: The Sandwich Pattern (In-Memory Transpilation)

The engine processes the Markdown, converts it to HTML, and places it into the @view system variable. This variable is then injected into your template block.

Because this happens entirely in RAM using Pointer Passing, the "Sandwiching" of content between your header and footer has zero measurable performance overhead.