htmlang

A minimalist layout language inspired by elm-ui that compiles to static HTML.

@ means structure. Bare lines mean content. No CSS required.

Example

@page My Site
@let primary #3b82f6

@fn card $title
  @el [padding 20, background white, rounded 8, border 1 #e5e7eb, hover:border 1 $primary, transition all 0.15s ease]
    @text [bold] $title
    @children

@column [max-width 800, center-x, padding 40, spacing 20]
  @text [bold, size 32] Hello

  @paragraph
    Built with {@text [bold, color $primary] htmlang}.

  @row [wrap, spacing 10]
    @card [title Simple]
      Write layouts without CSS
    @card [title Fast]
      Compiles to a single HTML file

Compiles to a self-contained .html file with flexbox layout and generated CSS classes. No JavaScript, no external dependencies.

Install

cargo install --path .

Usage

Everyday workflow:

htmlang init                 # scaffold a new project
htmlang page.hl              # compile page.hl -> page.html
htmlang --watch page.hl      # recompile on change
htmlang serve .              # dev server with live reload
htmlang serve --https --cert cert.pem --key key.pem .
htmlang fmt page.hl          # format a file in place
htmlang check page.hl        # parse only, report diagnostics

More commands (run with --help for flags):

Command	Purpose
build [dir]	Compile every .hl under a directory
watch [path]	Watch mode without a server
serve [path]	Dev server with live reload (--https ready)
convert file.html	Convert HTML back to htmlang
new name	Scaffold a new page from a template
components	List @fn / @component definitions
deps file.hl	Print the include / import graph
dead-code [dir]	Report unused @fn / @let / @define
feed [dir]	Generate an Atom feed from @article pages
sitemap [dir]	Generate sitemap.xml
lint [path]	Run warnings-only checks, optional JSON output
stats file.hl	Compile-time statistics
preview file.hl	Open a one-off preview
diff a.hl b.hl	Diff two files at the AST level
export file.hl	Export to plain HTML (--format pdf planned)
repl	Interactive REPL for expressions
deploy	Preset-driven deploy helper
playground	Write a self-contained playground HTML
clean [dir]	Remove generated .html files
upgrade	Apply mechanical migrations to out-of-date .hl
outline file.hl	Print the document tree
explain CODE	Longer explanation of a diagnostic code
lsp	Launch the language server (stdio)
benchmark [dir]	Measure parse / codegen timing

Editor support

A VS Code extension with syntax highlighting and LSP integration is available in editors/vscode. The language server (htmlang-lsp) provides diagnostics, completions, and hover documentation.

Language overview

Elements

Element	Purpose
@row	Horizontal flex layout
@column	Vertical flex layout
@el	Generic container
@text	Styled inline text
@paragraph	Flowing text with inline elements
@image	Image
@link	Anchor
@raw	Verbatim HTML escape hatch
@form	Form container
@details	Disclosure widget
@summary	Summary for @details
@blockquote	Block quotation
@cite	Citation reference
@code	Inline code (monospace)
@pre	Preformatted text
@hr	Horizontal rule / divider
@figure	Figure with caption
@figcaption	Caption for @figure
@progress	Progress bar
@meter	Meter/gauge

Layout attributes

@row [spacing 20]                  -- gap between children
@row [gap-x 10, gap-y 20]         -- separate horizontal/vertical gaps
@el [padding 20]                   -- uniform padding (also padding-x, padding-y)
@el [width fill]                   -- take remaining space (also width 200, width shrink)
@el [center-x]                     -- center horizontally (also align-left, align-right)
@el [overflow hidden]              -- overflow behavior (hidden, scroll, auto)

Style attributes

@el [background #3b82f6, color white, rounded 8, border 1 #e5e7eb]
@text [bold, italic, underline, size 18, font Inter]
@el [opacity 0.5, cursor pointer, transition all 0.15s ease]
@el [shadow 0 2px 4px rgba(0,0,0,0.1)]
@paragraph [text-align center, line-height 1.5]

Positioning

@el [position relative]
  @el [position absolute, z-index 10]
    Overlay content

Pseudo-states and media prefixes

Prefix any style attribute with hover:, active:, or focus::

@el [background #3b82f6, hover:background #2563eb, active:background #1d4ed8]

Use dark: for dark mode and print: for print styles:

@el [background white, dark:background #1a1a2e, print:display none]

Variables and defines

@let primary #3b82f6              -- simple variable, used as $primary
@let greeting "Hello $name"       -- quoted string interpolation
@define card [padding 20, rounded 8]   -- attribute bundle, used as [$card]

Functions

@fn button $label
  @el [padding 12, background $primary, rounded 8]
    @text [color white, bold] $label
    @children                      -- slot for caller's children

@button [label Click me]

File includes

@include header.hl                -- inline another .hl file

Multi-line attributes

Attribute lists can span multiple lines:

@el [
  padding 20,
  background white,
  rounded 8,
  shadow 0 2px 4px rgba(0,0,0,0.1)
]
  Content here

Other features

• -- comments
• {@text [bold] inline} elements in text
• @el [attrs] > @link url single-child chaining
• [padding 20] bare attributes as implicit @el
• @raw """...""" for embedding arbitrary HTML/CSS/JS
• @image [inline] logo.svg inlines SVG content
• @each $name, $url in Home /, About /about destructuring
• @let large = $base * 2 computed variables
• [grid-template-areas "header main", grid-area header] named grid areas
• [animate fade-in 0.3s ease] animation shorthand
• [view-transition-name hero] View Transitions API
• [has(.active):background blue] :has() pseudo-selector
• @slot header / @slot content named slots in @fn
• @theme design tokens as runtime CSS custom properties
• VS Code snippets for common patterns

Documentation

See DESIGN.md for the full language specification.