Hallmark Skill System Architecture: How the Static Site Generator Organizes Content

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 manifest file located in the skills/ directory. According to 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:

# 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, 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, 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 might look like:

---
type: component
name: quote
---

> {{content}}

This component embeds into pages using the Handlebars partial syntax:

---
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 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 demonstrates how to manipulate node metadata:

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

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

---
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 – Skill manifest and entry points
• skills/hallmark/references/structure.md – Core concepts and processor documentation
• skills/hallmark/references/design-md.md – Page and node composition rules
• skills/hallmark/references/assets.md – Static asset handling guidelines

Summary

• Skills are self-contained content packages defined by 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}