HTX Guide · 1.5.0-alpha.2

Frontmatter

YAML document metadata in HTX.

HTX 1.5.0-alpha.2 (reference implementation 0.3.0-alpha.3) — Features below are available in the htx CLI unless noted as browser-only.

Status: Shipped in reference implementation 0.3.0-alpha.3 Syntax: YAML between --- delimiters at document start

Example

---
title: Administration Panel
layout: dashboard
author: HTX Team
tags: [ops, monitoring]
meta:
  version: "0.1"
  env: production
---

Rules

  1. Frontmatter MUST be the first bytes of the file (optional BOM excluded).
  2. Opening --- on line 1; closing --- before body.
  3. Parsed as YAML 1.2 subset (maps, lists, strings, numbers, booleans).
  4. Stored on root AST node as meta object.
  5. Compilers may use layout for profile selection; not interpreted by core parser.

AST mapping

{
  "type": "root",
  "meta": {
    "title": "Administration Panel",
    "layout": "dashboard"
  },
  "children": []
}

Use cases

Field Consumer
title HTML <title>, page heading default
layout Compiler profile / template selection
author, date Metadata, RSS, llms.txt
Custom keys Application-specific; preserved in AST

AI agent guidance

Agents SHOULD emit minimal frontmatter (title, layout) unless the schema requires more. Prefer stable keys over deep nesting.

Prior art

  • Jekyll/Hugo/Zola frontmatter (YAML/TOML)
  • Markdoc document variables (separate from body)
  • Djot document attributes (different syntax)