# Hallmark Skill System Architecture: How the Static Site Generator Organizes Content > Explore Hallmark's skill system architecture. Learn how this static site generator organizes content into self-contained skills with markdown, data, and assets managed by Instagit. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: architecture - Published: 2026-08-17 --- **Hallmark's skill system architecture treats every piece of content as a self-contained skill—a hierarchical collection of nodes (markdown files, data, assets, and configuration) wired together by a tiny runtime supplied by Instagit.** The `Nutlope/hallmark` repository implements a unique static site generator built around a declarative **skill system** that modularizes content into reusable, composable units. Unlike traditional static generators that rely on rigid directory conventions, Hallmark's architecture centers on explicit manifest files and atomic content nodes that declare their dependencies upfront. ## Core Architectural Components ### Skills as Top-Level Packages At the highest level, Hallmark organizes content into **skills**—discrete packages defined by a [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) manifest file located in the `skills/` directory. According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), a skill acts as a collection of related markdown, configuration, and assets that define a piece of content or functionality. The manifest declares the skill's name, description, and entry points: ```markdown # Skill: Example description: A minimal example skill demonstrating the core concepts. pages: - path: /hello node: hello.md ``` ### Nodes as Atomic Content Units The **Node** represents the basic unit of the Hallmark skill system architecture. As documented in [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md), nodes are markdown or data files carrying a front-matter block that describes their type, imports, and metadata. Nodes support four primary types: - **`type: page`** – Top-level entry points that map URL paths to rendering pipelines - **`type: component`** – Reusable fragments embeddable via Handlebars syntax (`{{> component}}`) - **`type: data`** – JSON or YAML files providing structured content - **`type: asset`** – Static files (images, SVGs, fonts) copied verbatim to the output directory ### Pages, Components, and Templates **Pages** serve as special node types that act as rendering entry points, assembling trees of child nodes into complete HTML documents. As defined in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md), pages select **templates**—Handlebars-compatible layouts stored in the `templates/` directory—that determine how node content is wrapped. Components enable composition within the skill system architecture. A component node defined in [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md) might look like: ```markdown --- type: component name: quote --- > {{content}} ``` This component embeds into pages using the Handlebars partial syntax: ```markdown --- type: page title: Quotes template: default --- {{> components/quote content="Design is not just what it looks like."}} ``` ## The Skill System Processing Pipeline ### Discovery and Manifest Parsing The Hallmark skill system architecture follows a five-stage build process. First, the **discovery** phase walks the `skills/` directory to locate each [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) manifest. The runtime parses these manifests to identify available nodes, processors, and routing configurations. ### Node Processing and Dependency Resolution During the **parsing** phase, each node file undergoes front-matter extraction. The body content passes to appropriate **processors**—JavaScript functions typically stored in `scripts/` directories that transform raw content into renderable HTML. Nodes declare dependencies via `requires:` or `imports:` fields in their front-matter. The runtime constructs a directed acyclic graph (DAG) to guarantee correct processing order, ensuring that referenced components and data nodes resolve before dependent pages render. A custom processor example from [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) demonstrates how to manipulate node metadata: ```javascript // skills/example/scripts/timestamp.js export function process(node) { node.meta.generatedAt = new Date().toISOString(); return node; } ``` To apply this processor, reference it in the node's front-matter: ```markdown --- type: page processor: ./scripts/timestamp.js --- Page content here... ``` ### Rendering and Output Generation The **rendering** phase executes when a page node selects its template. The template receives the rendered HTML of child nodes as context variables, producing the final markup through Handlebars compilation. Finally, the **emission** phase writes generated HTML, CSS, and assets to the `public/` output folder, preserving custom routing defined in skill manifests. ## Practical Skill System Implementation Creating new content in Hallmark's architecture requires no additional code unless implementing custom processors. A complete skill implementation follows this structure: ```markdown --- type: page title: Hello World template: default --- Welcome to Hallmark! This page is built from a **page node**. ``` The system processes this through the pipeline defined in the core architecture files: - [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) – Skill manifest and entry points - [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) – Core concepts and processor documentation - [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) – Page and node composition rules - [`skills/hallmark/references/assets.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/assets.md) – Static asset handling guidelines ## Summary - **Skills** are self-contained content packages defined by [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) manifests in the `skills/` directory. - **Nodes** are atomic units (pages, components, data, assets) with typed front-matter declaring their role and dependencies. - **Pages** serve as top-level entry points that assemble child nodes into complete HTML documents using Handlebars templates. - **Processors** are JavaScript functions that transform node content during the build pipeline, supporting custom transformations without modifying core generator code. - The architecture follows a five-phase pipeline: Discovery → Parsing → Dependency Resolution → Rendering → Emission, outputting static files to `public/`. ## Frequently Asked Questions ### What file defines a skill in Hallmark's architecture? The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) file serves as the skill manifest, located at the root of each skill directory under `skills/`. This file declares the skill's metadata, available pages, and routing configuration that the Hallmark runtime uses during the discovery phase. ### How do nodes communicate dependencies in the Hallmark skill system? Nodes declare dependencies through front-matter fields like `requires:` or `imports:`, specifying paths to other nodes, components, or data files. The runtime builds a directed acyclic graph from these declarations to ensure components render before the pages that embed them. ### Can I extend Hallmark's skill system with custom processing logic? Yes, by creating JavaScript processor files in a skill's `scripts/` directory and referencing them via the `processor:` front-matter field in any node. These functions receive the node object as an argument and must return the modified node, allowing arbitrary transformations during the build process. ### What template engine does Hallmark use for rendering? Hallmark uses Handlebars-compatible templates stored in the `templates/` directory. The system supports partials via the `{{> component}}` syntax, enabling component composition within pages while maintaining strict separation between content nodes and presentation logic.