HTX Guide · 1.5.0-alpha.2

Syntax reference

Block directives, inline tags, nesting, and diagnostics at a glance.

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.

Quick reference for HTX 1.5.0-alpha.1 (reference implementation 0.3.0-alpha.3). Normative spec: specification. Tutorial: quickstart. Capability matrix: what’s available.

Block directives

::tag [optional-arg] { .class #id key="value" }
  Block content (Markdown + nested :: blocks)
::

Tag kind	Example	HTML (default profile)
HTML5	`::section { #main }`	`<section id="main">`
Layout	`::grid { .grid-cols-3 .gap-6 }`	`<div class="grid grid-cols-3 gap-6">`
Card	`::card [Title] { .x }`	`<div class="card x"><h3>Title</h3>…`
Component	`::component [Alert] { variant="warning" }`	Registered component output

HTML5 allowlist: section, article, aside, nav, header, footer, main, div, figure, figcaption, details, summary

Inline directives

:span{.text-green}[Operational]

CommonMark subset

# Heading
**bold** *italic* ~~strike~~ `code`
- list item
[link](https://example.com)

GFM tables and task lists are available via the optional GFM plugin: htx compile --gfm.

Semantic cross-references use (@id) — see semantic references.

Frontmatter

---
title: My Doc
layout: dashboard
---

Nesting

::row { .gap-4 }
  ::card [A]
    Item one
  ::
  ::card [B]
    Item two
  ::
::

Parse modes

Mode	Behavior	CLI flag
`strict`	Error on unclosed `::` block (`HTX002`)	default
`streaming`	Auto-close tail block (`HTX002W` warning)	`--streaming`
`content-only`	Strip directives from untrusted input	`--security-profile content-only`
`untrusted-data`	Quarantine content in `::data` blocks	`--security-profile untrusted-data`

Diagnostics

Exact message strings for conformance: specification §4.1. Full table: diagnostics.

Code	Meaning
`HTX001`	Extra `::` close
`HTX002`	Unclosed block at EOF
`HTX002W`	Streaming-mode auto-close warning
`HTX003`	Used `:::` instead of `::`
`HTX004`	Malformed attribute block
`HTX005`	Duplicate `#id` in one attribute block
`HTX006`	Invalid frontmatter YAML
`HTX007`	Inline directive nesting depth > 8
`HTX008`	Unregistered custom tag
`HTX009`	Unknown attribute on registered tag
`HTX010`–`HTX012`	Semantic reference errors
`HTX013`	Missing `type` on `::data`
`HTX014`	Unknown slot on registered component

Tag registry

Custom ::tag names can be registered with typed attribute schemas. Unregistered tags emit HTX008 (warning by default, error in strict registry mode).

Trust and security

AST nodes carry trust: "trusted" | "untrusted" | "derived". Security profiles enforce boundaries at parse time; see security profiles.

Not in core grammar

Footnotes, raw HTML pass-through, reference-style Markdown links, MDX/JSX, and layout shorthand remain out of scope. GFM tables/tasks require --gfm. Layout shorthand may ship as an optional preprocessor plugin.