HTX Guide · 1.5.0-alpha.2

Quickstart

Learn HTX core syntax in about 30 minutes.

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.

Learn HTX core syntax in ~30 minutes. Normative reference: specification.

1. Plain Markdown still works

# Hello HTX

This is a paragraph with **bold**, *italic*, and `inline code`.

- List item one
- List item two

[Link](https://example.com)

HTX uses a CommonMark subset — not every Markdown feature, but the familiar basics.

2. Add structure with :: blocks

::section { #hero .p-8 }
  ## Welcome

  Your content here.
::
  • ::tagname opens a block
  • :: on its own line closes it
  • { } holds attributes: .class, #id, key="value"

Common mistake (Djot users): HTX uses :: not ::: — three colons trigger error HTX003.

3. Layout tags

::grid { .grid-cols-3 .gap-6 }
  ::card [Database] { .border-blue }
    Status: **healthy**
  ::
  ::card [Cache] { .border-amber }
    Status: **degraded**
  ::
  ::card [Storage] { .border-blue }
    Capacity: **4.2 TB**
  ::
::

Custom tags (grid, card, row) compile to <div class="grid"> etc. The card tag uses [Title] as an <h3> heading.

4. Inline styling without HTML

Status: :span{.text-green}[Operational]

Equivalent to <span class="text-green">Operational</span> without angle brackets.

5. Document metadata (frontmatter)

---
title: My Dashboard
layout: dashboard
---

# My Dashboard

YAML between --- delimiters at file start. Parsed into AST meta on the root node.

6. Nesting

::row { .gap-4 }
  ::card [Metrics]
    * CPU: 12%
    * RAM: 64%
  ::
::

Inner blocks must close before outer blocks. Indentation is for readability only — structure comes from ::.

7. Try it

In the browser — open the playground or the admin dashboard example.

With the CLI (after building from source):

htx parse my-document.htx --ast
htx compile my-document.htx -o output.html

See also: grid layout example.

Coming from Markdown

Markdown HTX Notes
# Heading Same ATX only, no underlines
**bold** Same
Raw <div class="x"> ::div { .x } No HTML pass-through
--- horizontal rule Same Not frontmatter after body starts
Tables GFM plugin htx compile --gfm (see examples)

Coming from HTML

HTML HTX
<section id="x" class="a b"> ::section { #x .a .b }
<div class="card"><h3>Title</h3> ::card [Title]
<span class="green"> :span{.green}[text]

Coming from MDX

MDX lets you write React components and JavaScript. HTX does not.

// MDX — NOT HTX
import { Chart } from './Chart'
<Chart data={metrics} />
// HTX — declarative, no imports
::card [Metrics]
  CPU: **12%**
::

If you need components, HTX maps ::component tags to a static registry — no arbitrary code in documents. See slots-and-components.md and the components example.

Coming from Djot

Djot HTX
::: fenced divs ::tag ... ::
{#id .class} before block {#id .class} on :: open line
Line-local parsing Same goal — explicit :: close is even more local

Parse modes (tooling)

Mode When
strict Build, CI — errors on unclosed blocks
streaming Live preview — auto-closes open blocks (--streaming)
content-only Untrusted input — strips directives (--security-profile content-only)

Next steps