Format Specifications
Supported Content, Template & Config Formats
Input, template, configuration, and output formats across the three-stage pipeline.
Format Support Matrix
NucleusFlow processes structured text and templates through strict, memory-safe Rust parsers with deterministic resource budgets:
| Format Category | Specification / Syntax | Underlying Crate | Default Size Budget | Stage |
|---|---|---|---|---|
| Markdown Content | CommonMark + GitHub Flavored Markdown (GFM) | pulldown-cmark 0.13.5 | 10 MB (MAX_CONTENT_SIZE) | Stage 1 (MarkdownProcessor) |
| Document Frontmatter | YAML 1.2 (--- fenced header block) | noyalib 0.0.58 | 64 KB (max_metadata_size) | Stage 1 (MarkdownProcessor) |
| Layout Templates | Handlebars (.hbs) with partials & helpers | handlebars 6.2 | 1 MB (max_template_size) | Stage 2 (HandlebarsRenderer) |
| Pipeline Configuration | TOML (nucleusflow.toml) & Env Overrides | toml 0.9.5 + serde 1.0 | 1 MB (MAX_CONFIG_SIZE) | Core (ConfigBuilder) |
| Generated Markup | HTML5 + Schema.org JSON-LD + <meta> tags | minify-html 0.18.1 | 100 MB (max_output_size) | Stage 3 (HtmlGenerator) |
1. CommonMark & GitHub Flavored Markdown (GFM)
MarkdownProcessor uses pulldown-cmark 0.13.5 with GFM extensions enabled by default:
- GFM Tables (
ENABLE_TABLES): Pipe-delimited tables with column alignment (:---,:---:,---:). - Footnotes (
ENABLE_FOOTNOTES): Inline footnote references ([^1]) and bottom definition blocks. - Strikethrough (
ENABLE_STRIKETHROUGH): Double-tilde (~~deleted~~) inline formatting. - Automated Table of Contents (
with_toc()): Extracts heading hierarchies (h1throughh6), generates URL-safe slugs, and prepends a semantic<nav class="toc"><ul>...</ul></nav>block. - HTML Allowlist Sanitization (
with_sanitization()): Inspects inline HTML tags againstALLOWED_HTML_TAGS(p,div,span,h1..h6,ul,ol,li,a,img,code,pre,blockquote,em,strong,del,table,thead,tbody,tr,th,td,sup,sub,br,hr) and rejects suspicious patterns (<script,javascript:,data:,vbscript:,onclick,onerror,onload,eval().
2. YAML 1.2 Frontmatter (noyalib)
Every Markdown document may begin with a --- delimited YAML 1.2 frontmatter block parsed by noyalib 0.0.58:
---
title: "Deterministic Rust Pipelines"
author: "Sebastien Rousseau"
date: "2026-10-31"
description: "Guide to trait-based static site generation."
---
- Validation: Rejects empty frontmatter blocks and malformed YAML mappings with a typed
ProcessingError::InvalidFrontmatter. - Automatic Schema.org JSON-LD Synthesis: Valid frontmatter mappings are serialized into a
<script type="application/ld+json">block with@context: "https://schema.org"and@type: "Article"when rendered throughMarkdownProcessor.
3. Handlebars Templates (.hbs)
HandlebarsRenderer (HtmlTemplateRenderer) compiles .hbs templates using handlebars 6.2 and caches compiled templates inside an Arc<parking_lot::RwLock<Handlebars>>:
- Context Variables: Standard page fields (
title,description,content,author,date) and custom metadata key-value pairs. - Reusable Partials (
with_partial): Register shared layout components such as headers, footers, and navigation menus. - Custom Helpers (
with_helper/TemplateHelpertrait): Implement theTemplateHelpertrait (fn execute(&self, args: &[Value]) -> Result<Value, ProcessingError>) or use the built-inUppercaseHelper. - Strict Mode (
with_strict_mode): Verifies that every{{variable}}referenced in the template exists in the rendering context before execution, returningProcessingError::TemplateDataErrorif any required key is missing. - Balanced Brace Verification: Pre-validates template syntax for matching
{{and}}delimiters before invoking the compiler.
4. HTML5 Output & Minification
HtmlGenerator (HtmlOutputGenerator) transforms rendered template output into production-ready HTML5 files:
- HTML5 Structural Validation: Validates tag nesting and closing order while properly recognizing HTML5 void elements (
area,base,br,col,embed,hr,img,input,link,meta,param,source,track,wbr) and optional-closing elements (p,dt,dd,li,option,thead,th,tbody,tr,td,tfoot,colgroup). - Escaped
<meta>Injection (with_meta_tags): Escapes&,<,>,", and'in metadata keys and values and injects<meta name="..." content="...">into<head>. - Sub-10 µs Minification (
with_minification): Usesminify-html0.18.1 to minify HTML, inline CSS (minify_css: true), and inline JavaScript (minify_js: true) while preserving closing tags for strict validator compatibility. - Pretty-Printing (
without_minification): Indents nested HTML elements cleanly for local debugging and snapshot inspection.
5. Multi-Environment Configuration (nucleusflow.toml)
ConfigBuilder loads TOML configuration files, validates numerical bounds, and optionally applies environment variable overrides:
profile = "production"
[content]
max_content_size = 10485760
max_metadata_size = 65536
allowed_extensions = ["md", "markdown"]
validate_markdown = true
allow_html = false
[templates]
max_template_size = 1048576
cache_ttl = 3600
max_cache_size = 104857600
allowed_extensions = ["hbs", "handlebars"]
[output]
max_output_size = 104857600
file_permissions = 0o644
create_Backup = false
max_concurrent_ops = 10
[custom]
site_url = "https://nucleusflow.com"