@@ -18,40 +18,48 @@ This document will walk through the basics of Sail and its syntax.
1818
1919It’s easy to see how Sail can directly translate to HTML:
2020
21−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead>
22−<tbody><tr><td><pre class="language-hoon">
23−;html
24− ;head
25− ;title: My page
26− ;meta(charset "utf-8");
27− ==
28− ;body
29− ;h1: Welcome!
30− ;p
31− ; Hello, world!
32− ; Welcome to my page.
33− ; Here is an image:
34− ;br;
35− ;img@"/foo.png";
21+{% table %}
22+
23+- Sail
24+- HTML
25+
26+---
27+
28+- ```
29+ ;html
30+ ;head
31+ ;title: My page
32+ ;meta(charset "utf-8");
33+ ==
34+ ;body
35+ ;h1: Welcome!
36+ ;p
37+ ; Hello, world!
38+ ; Welcome to my page.
39+ ; Here is an image:
40+ ;br;
41+ ;img@"/foo.png";
42+ ==
3643 ==
3744 ==
38−==
39−</pre></td><td><pre>
40−&lt;html>
41− &lt;head>
42− &lt;title>My page&lt;/title>
43− &lt;meta charset="utf-8" />
44− &lt;/head>
45− &lt;body>
46− &lt;h1>Welcome!&lt;/h1>
47− &lt;p>Hello, world! Welcome to my
48− page. Here is an image:
49− &lt;br />
50− &lt;img src="/foo.png" />
51− &lt;/p>
52− &lt;/body>
53−&lt;/html>
54−</pre></td></tr></tbody></table>
45+ ```
46+- ```
47+ <html>
48+ <head>
49+ <title>My page</title>
50+ <meta charset="utf-8" />
51+ </head>
52+ <body>
53+ <h1>Welcome!</h1>
54+ <p>Hello, world! Welcome to my
55+ page. Here is an image:
56+ <br />
57+ <img src="/foo.png" />
58+ </p>
59+ </body>
60+ </html>
61+ ```
62+ {% /table %}
5563
5664## Tags and Closing
5765
@@ -63,17 +71,17 @@ close expressions; Sail inherits this convenience.
6371### Empty
6472
6573Empty tags are closed with a `;` following the tag. For example, `;div;` will be
66−rendered as `<div></div>`. Non-container tags `;br;` and `;img@"some-url";` in
67−particular will be rendered as a single tag like `<br />` and `<img src="some-url" />`.
74+rendered as `<div></div>`. Non-container tags `;br;` and `;img@"some-url";` in
75+particular will be rendered as a single tag like `<br />` and `<img src="some-url" />`.
6876
6977### Filled
7078
7179Filled tags are closed via line-break. To fill text inside, add `:` after the
7280tag name, then insert your plain text following a space. Example:
7381
74−| Sail | HTML |
75−| ---------------- | -------------------------- |
76−| `;h1: The title` | `<h1>The title</h1>` |
82+| Sail | HTML |
83+| ---------------- | -------------------- |
84+| `;h1: The title` | `<h1>The title</h1>` |
7785
7886### Nested
7987
@@ -81,41 +89,57 @@ To nest tags, simply create a new line. Nested tags need to be closed with `==`,
8189because they expect a list of sub-tags.
8290
8391If we nest lines of plain text with no tag, the text will be wrapped in a
84−`<p>` tag. Additionally, any text with atom auras or `++arm:syntax` in such
85−plain text lines will be wrapped in `<code>` tags.
92+`<p>` tag. Additionally, any text with atom auras or `++arm:syntax` in such
93+plain text lines will be wrapped in `<code>` tags.
8694
8795Example:
8896
89−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
90−<pre class="language-hoon">
91−;body
92− ;h1: Blog title
93− This is some good content.
94−==
95−</pre></td><td><pre>
96−&lt;body>
97− &lt;h1>Blog title&lt;/h1>
98− &lt;p>This is some good content.&lt;/p>
99−&lt;/body>
100−</pre></td></tr></tbody></table>
97+{% table %}
98+
99+- Sail
100+- HTML
101+
102+---
103+
104+- ```
105+ ;body
106+ ;h1: Blog title
107+ This is some good content.
108+ ==
109+ ```
110+- ```
111+ <body>
112+ <h1>Blog title</h1>
113+ <p>This is some good content.</p>
114+ </body>
115+ ```
116+ {% /table %}
101117
102118If we want to write a string with no tag at all, then we can prepend
103119those untagged lines with `;` and then a space:
104120
105−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
106−<pre class="language-hoon">
107−;body
108− ;h1: Welcome!
109− ; Hello, world!
110− ; We’re on the web.
111−==
112−</pre></td><td><pre>
113−&lt;body>
114− &lt;h1>Welcome!&lt;/h1>
115− Hello, world!
116− We’re on the web.
117−&lt;/body>
118−</pre></td></tr></tbody></table>
121+{% table %}
122+
123+- Sail
124+- HTML
125+
126+---
127+
128+- ```
129+ ;body
130+ ;h1: Welcome!
131+ ; Hello, world!
132+ ; We’re on the web.
133+ ==
134+ ```
135+- ```
136+ <body>
137+ <h1>Welcome!</h1>
138+ Hello, world!
139+ We’re on the web.
140+ </body>
141+ ```
142+ {% /table %}
119143
120144## Attributes
121145
@@ -129,78 +153,99 @@ shown below.
129153
130154### Generic
131155
132−<table><thead><tr><th>Form</th><th>Example</th></tr></thead><tbody>
133−<tr><td>Wide</td><td><pre class="language-hoon">
134−;div(title "a tooltip", style "color:red")
135− ;h1: Foo
136− foo bar baz
137−==
138−</pre></td></tr>
139−<tr><td>Tall</td><td><pre class="language-hoon">
140−;div
141− =title "a tooltip"
142− =style "color:red"
143− ;h1: Foo
144− foo bar baz
145−==
146−</pre></td></tr>
147−<tr><td>HTML</td><td><pre>
148−&lt;div title="a tooltip" style="color:red">
149− &lt;h1>Foo&lt;/h1>
150− &lt;p>foo bar baz &lt;/p>
151−&lt;/div>
152−</pre></td></tr></tbody></table>
156+{% table %}
157+
158+- Form
159+- Example
160+
161+---
162+
163+- Wide
164+- ```
165+ ;div(title "a tooltip", style "color:red")
166+ ;h1: Foo
167+ foo bar baz
168+ ==
169+ ```
170+ ***
171+- Tall
172+- ```
173+ ;div
174+ =title "a tooltip"
175+ =style "color:red"
176+ ;h1: Foo
177+ foo bar baz
178+ ==
179+ ```
180+ ***
181+- HTML
182+- ```
183+ <div title="a tooltip" style="color:red">
184+ <h1>Foo</h1>
185+ <p>foo bar baz </p>
186+ </div>
187+ ```
188+ {% /table %}
153189
154190### IDs
155191
156192Add `#` after tag name to add an ID:
157193
158−| Sail | HTML |
159−| ------------------- | ----------------------------------- |
160−| `;nav#header: Menu` | `<nav id="header">Menu</nav>` |
194+| Sail | HTML |
195+| ------------------- | ----------------------------- |
196+| `;nav#header: Menu` | `<nav id="header">Menu</nav>` |
161197
162198### Classes
163199
164200Add `.` after tag name to add a class:
165201
166−| Sail | HTML |
167−| ---------------------- | ---------------------------------------- |
168−| `;h1.text-blue: Title` | `<h1 class="text-blue">Title</h1>` |
202+| Sail | HTML |
203+| ---------------------- | ---------------------------------- |
204+| `;h1.text-blue: Title` | `<h1 class="text-blue">Title</h1>` |
169205
170206For class values containing spaces, you can add additional `.`s like so:
171207
172−| Sail | HTML |
173−| ------------------- | --------------------------------------- |
174−| `;div.foo.bar.baz;` | `<div class="foo bar baz"></div>` |
208+| Sail | HTML |
209+| ------------------- | --------------------------------- |
210+| `;div.foo.bar.baz;` | `<div class="foo bar baz"></div>` |
175211
176212Otherwise, if your class value does not conform to the allowed `@tas`
177213characters, you must use the generic attribute syntax:
178214
179−| Sail | HTML |
180−| ------------------------ | ----------------------------------- |
181−| `;div(class "!!! !!!");` | `<div class="!!! !!!"></div>` |
215+| Sail | HTML |
216+| ------------------------ | ----------------------------- |
217+| `;div(class "!!! !!!");` | `<div class="!!! !!!"></div>` |
182218
183219### Images
184220
185221Add `@` after the tag name to link your source:
186222
187−| Sail | HTML |
188−| --------------------- | ----------------------------- |
189−| `;img@"example.png";` | `<img src="example.png"/>` |
223+| Sail | HTML |
224+| --------------------- | -------------------------- |
225+| `;img@"example.png";` | `<img src="example.png"/>` |
190226
191227To add attributes to the image, like size specifications, add the desired
192228attribute after the `"` of the image name and before the final `;` of the `img`
193−tag like ;img@"example.png"(width "100%");`.
229+tag like `;img@"example.png"(width "100%");`.
194230
195231### Links
196232
197233Add `/` after tag name to start an `href`.
198234
199−<table><tr><th>Sail</th></tr><tr><td><pre class="language-hoon">
200−;a/"urbit.org": A link to Urbit.org
201−</pre></td></tr><tr><th>HTML</th></tr><tr><td><pre>
202−&lt;a href="urbit.org">A link to Urbit.org&lt;/a>
203−</pre></td></tr></table>
235+{% table %}
236+
237+- Sail
238+- HTML
239+
240+---
241+
242+- ```
243+ ;a/"urbit.org": A link to Urbit.org
244+ ```
245+- ```
246+ <a href="urbit.org">A link to Urbit.org</a>
247+ ```
248+ {% /table %}
204249
205250## Interpolation
206251
@@ -208,29 +253,53 @@ The textual content of tags, despite not being enclosed in double-quotes, are
208253actually tapes. This means they support interpolated Hoon expressions in the
209254usual manner. For example:
210255
211−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
212−<pre class="language-hoon">
213−=| =time
214−;p: foo {&lt;time>} bar
215−</pre></td><td><pre>
216−&lt;p>foo ~2000.1.1 baz&lt;/p>
217−</pre></td></tr></tbody></table>
256+{% table %}
257+
258+- Sail
259+- HTML
260+
261+---
262+
263+- ```
264+ =| =time
265+ ;p: foo {<time>} bar
266+ ```
267+- ```
268+ <p>foo ~2000.1.1 baz</p>
269+ ```
270+ {% /table %}
218271
219272Likewise:
220273
221−<table><tr><th>Sail</th></tr><tr><td><pre class="language-hoon">
222−=/ txt=tape " bananas"
223−;article
224− ;b: {(a-co:co (mul 42 789))}
225− ; {txt}
226− {&lt;our>} {&lt;now>} {&lt;`@ux`(end 6 eny)>}
227−==
228−</pre></td></tr><tr><th>HTML</th></tr><tr><td><pre>
229−&lt;article>
230− &lt;b>33138&lt;/b> bananas
231− &lt;p>~zod ~2022.2.21..09.54.21..5b63 0x9827.99c7.06f4.8ef9&lt;/p>
232−&lt;/article>
233−</pre></td></tr></table>
274+{% table .w-full %}
275+
276+- Sail
277+
278+---
279+
280+- ```
281+ =/ txt=tape " bananas"
282+ ;article
283+ ;b: {(a-co:co (mul 42 789))}
284+ ; {txt}
285+ {<our>} {<now>} {<`@ux`(end 6 eny)>}
286+ ==
287+ ```
288+ {% /table %}
289+
290+{% table .w-full %}
291+
292+- HTML
293+
294+---
295+
296+- ```
297+ <article>
298+ <b>33138</b> bananas
299+ <p>~zod ~2022.2.21..09.54.21..5b63 0x9827.99c7.06f4.8ef9</p>
300+ </article>
301+ ```
302+ {% /table %}
234303
235304## A note on CSS
236305
@@ -316,7 +385,7 @@ elements, converting characters such as `>` to HTML entities. For example:
316385> =z ;p(class "\"><script src=\"example.com/xxx.js"): <h1>FOO</h1>
317386
318387> (crip (en-xml:html z))
319−'<p class=""><script src="example.com/xxx.js"><h1>FOO</h1></p>'
388+'<p class=""><script src="example.com/xxx.js"><h1>FOO</h1></p>'
320389```
321390
322391### Marks
@@ -338,7 +407,7 @@ the resulting `tape` through `++crip`.
338407- Type: `$manx`
339408
340409The `%hymn` mark is intended to be used for complete HTML documents - having an
341−`<html>` root element, `<head>`, `<body>`, etc. This isn't enforced on
410+`<html>` root element, `<head>`, `<body>`, etc. This isn't enforced on
342411the type level but it is assumed in certain mark conversion pathways. Eyre can
343412automatically convert a `%hymn` to printed `%html` if it was requested through
344413Eyre's scry interface.
@@ -399,25 +468,33 @@ The [mictar rune](/docs/hoon/reference/rune/mic#-mictar) makes a `$marl` (a list
399468of XML nodes) from a complex hoon expression. This rune lets you add many
400469elements inside another Sail element. For example:
401470
402−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
403−<pre class="language-hoon">
404−=/ nums=(list @ud) (gulf 1 9)
405−;p
406− ;* %+ turn nums
407− |= n=@ud
408− ?: =(0 (mod n 2))
409− ;sup: {(a-co:co n)}
410− ;sub: {(a-co:co n)}
411−==
412−</pre></td><td><pre>
413−&lt;p>
414− &lt;sub>1&lt;/sub>&lt;sup>2&lt;/sup>
415− &lt;sub>3&lt;/sub>&lt;sup>4&lt;/sup>
416− &lt;sub>5&lt;/sub>&lt;sup>6&lt;/sup>
417− &lt;sub>7&lt;/sub>&lt;sup>8&lt;/sup>
418− &lt;sub>9&lt;/sub>
419−&lt;/p>
420−</pre></td></tr></tbody></table>
471+{% table %}
472+
473+- Sail
474+- HTML
475+
476+---
477+
478+- ```
479+ =/ nums=(list @ud) (gulf 1 9)
480+ ;p
481+ ;* %+ turn nums
482+ |= n=@ud
483+ ?: =(0 (mod n 2))
484+ ;sup: {(a-co:co n)}
485+ ;sub: {(a-co:co n)}
486+ ==
487+ ```
488+- ```
489+ <p>
490+ <sub>1</sub><sup>2</sup>
491+ <sub>3</sub><sup>4</sup>
492+ <sub>5</sub><sup>6</sup>
493+ <sub>7</sub><sup>8</sup>
494+ <sub>9</sub>
495+ </p>
496+ ```
497+ {% /table %}
421498
422499### `;=` Mictis
423500
@@ -426,23 +503,31 @@ of XML nodes) from a series of `$manx`es. This is mostly useful if you want to
426503make the list outside of an element and then be able to insert it afterwards.
427504For example:
428505
429−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
430−<pre class="language-hoon">
431−=/ paras=marl
432− ;= ;p: First node.
433− ;p: Second node.
434− ;p: Third node.
506+{% table %}
507+
508+- Sail
509+- HTML
510+
511+---
512+
513+- ```
514+ =/ paras=marl
515+ ;= ;p: First node.
516+ ;p: Second node.
517+ ;p: Third node.
518+ ==
519+ ;main
520+ ;* paras
435521 ==
436−;main
437− ;* paras
438−==
439−</pre></td><td><pre>
440−&lt;main>
441− &lt;p>First node.&lt;/p>
442− &lt;p>Second node.&lt;/p>
443− &lt;p>Third node.&lt;/p>
444−&lt;/main>
445−</pre></td></tr></tbody></table>
522+ ```
523+- ```
524+ <main>
525+ <p>First node.</p>
526+ <p>Second node.</p>
527+ <p>Third node.</p>
528+ </main>
529+ ```
530+ {% /table %}
446531
447532### `;/` Micfas
448533