git.iko.soy/htmlang
on master help sign in
Add README with quick start guide and language overview
65ede41iko
README.mdnew file+113
compare with master
unifiedsplit
@@ -0,0 +1,113 @@
1+# htmlang
2+
3+A minimalist layout language inspired by [elm-ui](https://package.elm-lang.org/packages/mdgriffith/elm-ui/latest/) that compiles to static HTML.
4+
5+`@` means structure. Bare lines mean content. No CSS required.
6+
7+## Example
8+
9+```
10+@page My Site
11+@let primary #3b82f6
12+
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
17+
18+@column [max-width 800, center-x, padding 40, spacing 20]
19+ @text [bold, size 32] Hello
20+
21+ @paragraph
22+ Built with {@text [bold, color $primary] htmlang}.
23+
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+```
30+
31+Compiles to a self-contained `.html` file with flexbox layout and generated CSS classes. No JavaScript, no external dependencies.
32+
33+## Install
34+
35+```
36+cargo install --path .
37+```
38+
39+## Usage
40+
41+```
42+htmlang page.hl # writes page.html
43+```
44+
45+## Language overview
46+
47+### Elements
48+
49+| Element | Purpose |
50+|--------------|------------------------------|
51+| `@row` | Horizontal flex layout |
52+| `@column` | Vertical flex layout |
53+| `@el` | Generic container |
54+| `@text` | Styled inline text |
55+| `@paragraph` | Flowing text with inline elements |
56+| `@image` | Image |
57+| `@link` | Anchor |
58+| `@raw` | Verbatim HTML escape hatch |
59+
60+### Layout attributes
61+
62+```
63+@row [spacing 20] -- gap between children
64+@el [padding 20] -- uniform padding (also padding-x, padding-y)
65+@el [width fill] -- take remaining space (also width 200, width shrink)
66+@el [center-x] -- center horizontally (also align-left, align-right)
67+```
68+
69+### Style attributes
70+
71+```
72+@el [background #3b82f6, color white, rounded 8, border 1 #e5e7eb]
73+@text [bold, italic, underline, size 18, font Inter]
74+@el [opacity 0.5, cursor pointer, transition all 0.15s ease]
75+```
76+
77+### Pseudo-states
78+
79+Prefix any style attribute with `hover:`, `active:`, or `focus:`:
80+
81+```
82+@el [background #3b82f6, hover:background #2563eb, active:background #1d4ed8]
83+```
84+
85+### Variables and defines
86+
87+```
88+@let primary #3b82f6 -- simple variable, used as $primary
89+@define card [padding 20, rounded 8] -- attribute bundle, used as [$card]
90+```
91+
92+### Functions
93+
94+```
95+@fn button $label
96+ @el [padding 12, background $primary, rounded 8]
97+ @text [color white, bold] $label
98+ @children -- slot for caller's children
99+
100+@button [label Click me]
101+```
102+
103+### Other features
104+
105+- `--` comments
106+- `{@text [bold] inline}` elements in text
107+- `@el [attrs] > @link url` single-child chaining
108+- `[padding 20]` bare attributes as implicit `@el`
109+- `@raw """..."""` for embedding arbitrary HTML/CSS/JS
110+
111+## Documentation
112+
113+See [DESIGN.md](DESIGN.md) for the full language specification.