git.iko.soy/htmlang
on master help sign in
htmlang/examples/docs.hl
146 lines 5.2 kB history raw
1-- A documentation page: a sidebar built from data, prose in htmlang and in
2-- Markdown, code samples, a table, and a component with scoped styles.
3-- `@h2:` and `@td:` style every heading and cell inside an element, the
4-- ones Markdown writes included.
5@page [lang=en, color var(--ink)] Getting started · htmlang docs
7@let --ink #0f172a
8@let --muted #64748b
9@let --accent #3b82f6
10@let --line #e5e7eb
11@let --code-bg #f1f5f9
13-- The page this file renders, used to highlight it in the sidebar
14@let current install
16@data $sections [
17 {"title": "Introduction", "pages": [
18 {"id": "overview", "label": "Overview"},
19 {"id": "install", "label": "Getting started"},
20 {"id": "first-page", "label": "Your first page"}
21 ]},
22 {"title": "Guides", "pages": [
23 {"id": "layout", "label": "Layout"},
24 {"id": "styling", "label": "Styling"},
25 {"id": "functions", "label": "Functions"},
26 {"id": "data", "label": "Data and loops"}
27 ]}
30-- Code samples: the lines under @code are shown exactly as written, @ and all
31@let @code-block
32 @pre [padding 16, background var(--code-bg), border-radius 8, font-size 14, line-height 1.5, overflow-x auto]
33 @children
35-- A callout with its own stylesheet. The @style rules are scoped to the
36-- function's root element; & is the root itself.
37@let @callout [kind Note]
38 @style
39 & { border-inline-start: 4px solid var(--accent); }
40 .label { font-weight: 700; color: var(--accent); }
41 @aside [padding 12 16, spacing 4, background #eff6ff, border-radius 6]
42 @text [class=label] $kind
43 @children
45@row [height fill]
46 -- Sidebar
47 @aside [
48 width 260,
49 flex-shrink 0,
50 padding 32 20,
51 spacing 24,
52 background #fafafa,
53 border-right 1 solid var(--line),
54 display none,
55 md:display flex
56 ]
57 @link [font-weight 800, font-size 18] / htmlang
58 @nav [spacing 20]
59 @each $section in $sections
60 @el [spacing 4]
61 @text [font-size 12, font-weight 700, color var(--muted), text-transform uppercase, letter-spacing 1] $section.title
62 @each $item in $section.pages
63 @link [
64 padding 6 12,
65 border-radius 6,
66 hover:background var(--code-bg),
67 if($item.id == $current, [background var(--code-bg), font-weight 600, aria-current=page])
68 ] /docs/$item.id $item.label
70 -- Content
71 @main [width fill, padding 48 24, md:padding 48 56]
72 @article [max-width 760, spacing 20, line-height 1.7, @h2:[font-size 24, margin-block-start 16]]
73 @el [spacing 8]
74 @text [font-size 14, color var(--muted)] Introduction
75 @h1 [font-size 40, line-height 1.2] Getting started
77 @paragraph [font-size 18]
78 htmlang is a small layout language that compiles to static HTML. This
79 guide takes about five minutes: install the compiler, write a page,
80 and see it in the browser.
82 @h2 [id=install] Install
83 @code-block > @code
84 cargo install --path .
86 @h2 [id=first-page] Your first page
87 @paragraph
88 Create a file called {@code hello.hl}:
89 @code-block > @code
90 @page Hello
91 @el [padding 40, spacing 16]
92 @h1 Hi there
93 @paragraph
94 This is {@b htmlang}.
95 @paragraph
96 Then start the dev server and open the page. It recompiles and reloads
97 whenever you save; press {@kbd [padding 1 6, border 1 solid var(--line), border-radius 4, font-size 14] Ctrl+C} to stop it.
98 @code-block > @code
99 htmlang serve .
101 @callout [kind Tip]
102 @paragraph
103 The output is one {@code .html} file with its CSS inside and no
104 JavaScript, so you can open it straight from disk.
106 @h2 Commands
107 @table [
108 border-collapse collapse,
109 width 100%,
110 font-size 15,
111 @th:[padding 8, text-align left],
112 @td:padding 8,
113 @tr:border-bottom 1 solid var(--line),
114 @tr:last-child:border-bottom none
115 ]
116 @thead
117 @tr [border-bottom 2 solid var(--line)]
118 @th Command
119 @th What it does
120 @tbody
121 @tr
122 @td htmlang page.hl
123 @td Compile one file to page.html
124 @tr
125 @td htmlang serve .
126 @td Serve a folder with live reload
127 @tr
128 @td htmlang build src -o dist
129 @td Compile a whole site
130 @tr
131 @td htmlang check page.hl
132 @td Report problems without writing output
134 -- Longer prose can be Markdown, styled by the element around it
135 @section [@code:[padding 1 4, background var(--code-bg), border-radius 4], @li:margin-block 4]
136 @markdown
137 ## Next steps
139 - Read about **layout**: `@row`, `@el`, `spacing` and `width fill`.
140 - Style anything with CSS properties: `[padding 20, color navy]`.
141 - Turn repeated markup into functions with `@let @name`.
143 @row [spacing 12, padding-block-start 24, border-top 1 solid var(--line), font-weight 600, @link:color var(--accent)]
144 @link /docs/overview ← Overview
145 @spacer
146 @link /docs/first-page Your first page →