git.iko.soy/htmlang
on v2026.04.14.121554 help sign in
htmlang/README.md
150 lines 3.9 kB history raw
1# htmlang
3A minimalist layout language inspired by [elm-ui](https://package.elm-lang.org/packages/mdgriffith/elm-ui/latest/) that compiles to static HTML.
5`@` means structure. Bare lines mean content. No CSS required.
7## Example
9```
10@page My Site
11@let primary #3b82f6
13@fn card $title
14 @el [padding 20, background white, rounded 8, border 1 #e5e7eb, hover:border 1 $primary, transition all 0.15s ease]
15 @text [bold] $title
16 @children
18@column [max-width 800, center-x, padding 40, spacing 20]
19 @text [bold, size 32] Hello
21 @paragraph
22 Built with {@text [bold, color $primary] htmlang}.
24 @row [wrap, spacing 10]
25 @card [title Simple]
26 Write layouts without CSS
27 @card [title Fast]
28 Compiles to a single HTML file
29```
31Compiles to a self-contained `.html` file with flexbox layout and generated CSS classes. No JavaScript, no external dependencies.
33## Install
35```
36cargo install --path .
37```
39## Usage
41```
42htmlang page.hl # writes page.html
43htmlang --watch page.hl # recompile on change
44```
46## Editor support
48A VS Code extension with syntax highlighting and LSP integration is available in [`editors/vscode`](editors/vscode). The language server (`htmlang-lsp`) provides diagnostics, completions, and hover documentation.
50## Language overview
52### Elements
54| Element | Purpose |
55|--------------|------------------------------|
56| `@row` | Horizontal flex layout |
57| `@column` | Vertical flex layout |
58| `@el` | Generic container |
59| `@text` | Styled inline text |
60| `@paragraph` | Flowing text with inline elements |
61| `@image` | Image |
62| `@link` | Anchor |
63| `@raw` | Verbatim HTML escape hatch |
65### Layout attributes
67```
68@row [spacing 20] -- gap between children
69@row [gap-x 10, gap-y 20] -- separate horizontal/vertical gaps
70@el [padding 20] -- uniform padding (also padding-x, padding-y)
71@el [width fill] -- take remaining space (also width 200, width shrink)
72@el [center-x] -- center horizontally (also align-left, align-right)
73@el [overflow hidden] -- overflow behavior (hidden, scroll, auto)
74```
76### Style attributes
78```
79@el [background #3b82f6, color white, rounded 8, border 1 #e5e7eb]
80@text [bold, italic, underline, size 18, font Inter]
81@el [opacity 0.5, cursor pointer, transition all 0.15s ease]
82@el [shadow 0 2px 4px rgba(0,0,0,0.1)]
83@paragraph [text-align center, line-height 1.5]
84```
86### Positioning
88```
89@el [position relative]
90 @el [position absolute, z-index 10]
91 Overlay content
92```
94### Pseudo-states
96Prefix any style attribute with `hover:`, `active:`, or `focus:`:
98```
99@el [background #3b82f6, hover:background #2563eb, active:background #1d4ed8]
100```
102### Variables and defines
104```
105@let primary #3b82f6 -- simple variable, used as $primary
106@define card [padding 20, rounded 8] -- attribute bundle, used as [$card]
107```
109### Functions
111```
112@fn button $label
113 @el [padding 12, background $primary, rounded 8]
114 @text [color white, bold] $label
115 @children -- slot for caller's children
117@button [label Click me]
118```
120### File includes
122```
123@include header.hl -- inline another .hl file
124```
126### Multi-line attributes
128Attribute lists can span multiple lines:
130```
131@el [
132 padding 20,
133 background white,
134 rounded 8,
135 shadow 0 2px 4px rgba(0,0,0,0.1)
137 Content here
138```
140### Other features
142- `--` comments
143- `{@text [bold] inline}` elements in text
144- `@el [attrs] > @link url` single-child chaining
145- `[padding 20]` bare attributes as implicit `@el`
146- `@raw """..."""` for embedding arbitrary HTML/CSS/JS
148## Documentation
150See [DESIGN.md](DESIGN.md) for the full language specification.