@@ -18,40 +18,48 @@ This document will walk through the basics of Sail and its syntax.
19It’s easy to see how Sail can directly translate to HTML:
19It’s easy to see how Sail can directly translate to HTML:
21−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead>
21+{% table %}
22−<tbody><tr><td><pre class="language-hoon">
22+
25− ;title: My page
31+ ;title: My page
26− ;meta(charset "utf-8");
32+ ;meta(charset "utf-8");
29− ;h1: Welcome!
35+ ;h1: Welcome!
31− ; Hello, world!
37+ ; Hello, world!
32− ; Welcome to my page.
38+ ; Welcome to my page.
33− ; Here is an image:
39+ ; Here is an image:
35− ;img@"/foo.png";
41+ ;img@"/foo.png";
39−</pre></td><td><pre>
46+- ```
40−&lt;html>
47+ <html>
41− &lt;head>
48+ <head>
42− &lt;title>My page&lt;/title>
49+ <title>My page</title>
43− &lt;meta charset="utf-8" />
50+ <meta charset="utf-8" />
44− &lt;/head>
51+ </head>
45− &lt;body>
52+ <body>
46− &lt;h1>Welcome!&lt;/h1>
53+ <h1>Welcome!</h1>
47− &lt;p>Hello, world! Welcome to my
54+ <p>Hello, world! Welcome to my
48− page. Here is an image:
55+ page. Here is an image:
49− &lt;br />
56+ <br />
50− &lt;img src="/foo.png" />
57+ <img src="/foo.png" />
51− &lt;/p>
58+ </p>
52− &lt;/body>
59+ </body>
53−&lt;/html>
60+ </html>
54−</pre></td></tr></tbody></table>
62+ {% /table %}
56## Tags and Closing
64## Tags and Closing
@@ -63,17 +71,17 @@ close expressions; Sail inherits this convenience.
65Empty tags are closed with a `;` following the tag. For example, `;div;` will be
73Empty 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
74+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" />`.
75+particular will be rendered as a single tag like `<br />` and `<img src="some-url" />`.
71Filled tags are closed via line-break. To fill text inside, add `:` after the
79Filled tags are closed via line-break. To fill text inside, add `:` after the
72tag name, then insert your plain text following a space. Example:
80tag name, then insert your plain text following a space. Example:
74−| Sail | HTML |
82+| Sail | HTML |
75−| ---------------- | -------------------------- |
83+| ---------------- | -------------------- |
76−| `;h1: The title` | `<h1>The title</h1>` |
84+| `;h1: The title` | `<h1>The title</h1>` |
@@ -81,41 +89,57 @@ To nest tags, simply create a new line. Nested tags need to be closed with `==`,
81because they expect a list of sub-tags.
89because they expect a list of sub-tags.
83If we nest lines of plain text with no tag, the text will be wrapped in a
91If 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
92+`<p>` tag. Additionally, any text with atom auras or `++arm:syntax` in such
85−plain text lines will be wrapped in `<code>` tags.
93+plain text lines will be wrapped in `<code>` tags.
89−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
97+{% table %}
90−<pre class="language-hoon">
98+
92− ;h1: Blog title
106+ ;h1: Blog title
93− This is some good content.
107+ This is some good content.
95−</pre></td><td><pre>
109+ ```
96−&lt;body>
111+ <body>
97− &lt;h1>Blog title&lt;/h1>
112+ <h1>Blog title</h1>
98− &lt;p>This is some good content.&lt;/p>
113+ <p>This is some good content.</p>
99−&lt;/body>
114+ </body>
100−</pre></td></tr></tbody></table>
116+ {% /table %}
102If we want to write a string with no tag at all, then we can prepend
118If we want to write a string with no tag at all, then we can prepend
103those untagged lines with `;` and then a space:
119those untagged lines with `;` and then a space:
105−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
121+{% table %}
106−<pre class="language-hoon">
122+
108− ;h1: Welcome!
130+ ;h1: Welcome!
109− ; Hello, world!
131+ ; Hello, world!
110− ; We’re on the web.
132+ ; We’re on the web.
112−</pre></td><td><pre>
134+ ```
113−&lt;body>
136+ <body>
114− &lt;h1>Welcome!&lt;/h1>
137+ <h1>Welcome!</h1>
115− Hello, world!
138+ Hello, world!
116− We’re on the web.
139+ We’re on the web.
117−&lt;/body>
140+ </body>
118−</pre></td></tr></tbody></table>
142+ {% /table %}
120## Attributes
144## Attributes
@@ -129,78 +153,99 @@ shown below.
130### Generic
154### Generic
132−<table><thead><tr><th>Form</th><th>Example</th></tr></thead><tbody>
156+{% table %}
133−<tr><td>Wide</td><td><pre class="language-hoon">
157+
134−;div(title "a tooltip", style "color:red")
165+ ;div(title "a tooltip", style "color:red")
135− ;h1: Foo
166+ ;h1: Foo
136− foo bar baz
167+ foo bar baz
138−</pre></td></tr>
169+ ```
139−<tr><td>Tall</td><td><pre class="language-hoon">
170+ ***
141− =title "a tooltip"
174+ =title "a tooltip"
142− =style "color:red"
175+ =style "color:red"
143− ;h1: Foo
176+ ;h1: Foo
144− foo bar baz
177+ foo bar baz
146−</pre></td></tr>
179+ ```
147−<tr><td>HTML</td><td><pre>
181+- HTML
148−&lt;div title="a tooltip" style="color:red">
183+ <div title="a tooltip" style="color:red">
149− &lt;h1>Foo&lt;/h1>
184+ <h1>Foo</h1>
150− &lt;p>foo bar baz &lt;/p>
185+ <p>foo bar baz </p>
151−&lt;/div>
186+ </div>
152−</pre></td></tr></tbody></table>
188+ {% /table %}
156Add `#` after tag name to add an ID:
192Add `#` after tag name to add an ID:
158−| Sail | HTML |
194+| Sail | HTML |
159−| ------------------- | ----------------------------------- |
195+| ------------------- | ----------------------------- |
160−| `;nav#header: Menu` | `<nav id="header">Menu</nav>` |
196+| `;nav#header: Menu` | `<nav id="header">Menu</nav>` |
162### Classes
198### Classes
164Add `.` after tag name to add a class:
200Add `.` after tag name to add a class:
166−| Sail | HTML |
202+| Sail | HTML |
167−| ---------------------- | ---------------------------------------- |
203+| ---------------------- | ---------------------------------- |
168−| `;h1.text-blue: Title` | `<h1 class="text-blue">Title</h1>` |
204+| `;h1.text-blue: Title` | `<h1 class="text-blue">Title</h1>` |
170For class values containing spaces, you can add additional `.`s like so:
206For class values containing spaces, you can add additional `.`s like so:
172−| Sail | HTML |
208+| Sail | HTML |
173−| ------------------- | --------------------------------------- |
209+| ------------------- | --------------------------------- |
174−| `;div.foo.bar.baz;` | `<div class="foo bar baz"></div>` |
210+| `;div.foo.bar.baz;` | `<div class="foo bar baz"></div>` |
176Otherwise, if your class value does not conform to the allowed `@tas`
212Otherwise, if your class value does not conform to the allowed `@tas`
177characters, you must use the generic attribute syntax:
213characters, you must use the generic attribute syntax:
179−| Sail | HTML |
215+| Sail | HTML |
180−| ------------------------ | ----------------------------------- |
216+| ------------------------ | ----------------------------- |
181−| `;div(class "!!! !!!");` | `<div class="!!! !!!"></div>` |
217+| `;div(class "!!! !!!");` | `<div class="!!! !!!"></div>` |
183### Images
219### Images
185Add `@` after the tag name to link your source:
221Add `@` after the tag name to link your source:
187−| Sail | HTML |
223+| Sail | HTML |
188−| --------------------- | ----------------------------- |
224+| --------------------- | -------------------------- |
189−| `;img@"example.png";` | `<img src="example.png"/>` |
225+| `;img@"example.png";` | `<img src="example.png"/>` |
191To add attributes to the image, like size specifications, add the desired
227To add attributes to the image, like size specifications, add the desired
192attribute after the `"` of the image name and before the final `;` of the `img`
228attribute 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%");`.
197Add `/` after tag name to start an `href`.
233Add `/` after tag name to start an `href`.
199−<table><tr><th>Sail</th></tr><tr><td><pre class="language-hoon">
235+{% table %}
200−;a/"urbit.org": A link to Urbit.org
243+ ;a/"urbit.org": A link to Urbit.org
201−</pre></td></tr><tr><th>HTML</th></tr><tr><td><pre>
244+ ```
202−&lt;a href="urbit.org">A link to Urbit.org&lt;/a>
246+ <a href="urbit.org">A link to Urbit.org</a>
203−</pre></td></tr></table>
248+ {% /table %}
205## Interpolation
250## Interpolation
@@ -208,29 +253,53 @@ The textual content of tags, despite not being enclosed in double-quotes, are
208actually tapes. This means they support interpolated Hoon expressions in the
253actually tapes. This means they support interpolated Hoon expressions in the
209usual manner. For example:
254usual manner. For example:
211−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
256+{% table %}
212−<pre class="language-hoon">
257+
213−=| =time
264+ =| =time
214−;p: foo {&lt;time>} bar
265+ ;p: foo {<time>} bar
215−</pre></td><td><pre>
266+ ```
216−&lt;p>foo ~2000.1.1 baz&lt;/p>
268+ <p>foo ~2000.1.1 baz</p>
217−</pre></td></tr></tbody></table>
270+ {% /table %}
221−<table><tr><th>Sail</th></tr><tr><td><pre class="language-hoon">
274+{% table .w-full %}
222−=/ txt=tape " bananas"
281+ =/ txt=tape " bananas"
223−;article
282+ ;article
224− ;b: {(a-co:co (mul 42 789))}
283+ ;b: {(a-co:co (mul 42 789))}
226− {&lt;our>} {&lt;now>} {&lt;`@ux`(end 6 eny)>}
285+ {<our>} {<now>} {<`@ux`(end 6 eny)>}
228−</pre></td></tr><tr><th>HTML</th></tr><tr><td><pre>
287+ ```
229−&lt;article>
297+ <article>
230− &lt;b>33138&lt;/b> bananas
298+ <b>33138</b> bananas
231− &lt;p>~zod ~2022.2.21..09.54.21..5b63 0x9827.99c7.06f4.8ef9&lt;/p>
299+ <p>~zod ~2022.2.21..09.54.21..5b63 0x9827.99c7.06f4.8ef9</p>
232−&lt;/article>
300+ </article>
233−</pre></td></tr></table>
302+ {% /table %}
235## A note on CSS
304## A note on CSS
@@ -316,7 +385,7 @@ elements, converting characters such as `>` to HTML entities. For example:
316> =z ;p(class "\"><script src=\"example.com/xxx.js"): <h1>FOO</h1>
385> =z ;p(class "\"><script src=\"example.com/xxx.js"): <h1>FOO</h1>
318> (crip (en-xml:html z))
387> (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>'
@@ -338,7 +407,7 @@ the resulting `tape` through `++crip`.
338- Type: `$manx`
407- Type: `$manx`
340The `%hymn` mark is intended to be used for complete HTML documents - having an
409The `%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
342the type level but it is assumed in certain mark conversion pathways. Eyre can
411the type level but it is assumed in certain mark conversion pathways. Eyre can
343automatically convert a `%hymn` to printed `%html` if it was requested through
412automatically convert a `%hymn` to printed `%html` if it was requested through
344Eyre's scry interface.
413Eyre's scry interface.
@@ -399,25 +468,33 @@ The [mictar rune](/docs/hoon/reference/rune/mic#-mictar) makes a `$marl` (a list
399of XML nodes) from a complex hoon expression. This rune lets you add many
468of XML nodes) from a complex hoon expression. This rune lets you add many
400elements inside another Sail element. For example:
469elements inside another Sail element. For example:
402−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
471+{% table %}
403−<pre class="language-hoon">
472+
404−=/ nums=(list @ud) (gulf 1 9)
479+ =/ nums=(list @ud) (gulf 1 9)
406− ;* %+ turn nums
481+ ;* %+ turn nums
407− |= n=@ud
482+ |= n=@ud
408− ?: =(0 (mod n 2))
483+ ?: =(0 (mod n 2))
409− ;sup: {(a-co:co n)}
484+ ;sup: {(a-co:co n)}
410− ;sub: {(a-co:co n)}
485+ ;sub: {(a-co:co n)}
412−</pre></td><td><pre>
487+ ```
413−&lt;p>
488+- ```
414− &lt;sub>1&lt;/sub>&lt;sup>2&lt;/sup>
489+ <p>
415− &lt;sub>3&lt;/sub>&lt;sup>4&lt;/sup>
490+ <sub>1</sub><sup>2</sup>
416− &lt;sub>5&lt;/sub>&lt;sup>6&lt;/sup>
491+ <sub>3</sub><sup>4</sup>
417− &lt;sub>7&lt;/sub>&lt;sup>8&lt;/sup>
492+ <sub>5</sub><sup>6</sup>
418− &lt;sub>9&lt;/sub>
493+ <sub>7</sub><sup>8</sup>
419−&lt;/p>
494+ <sub>9</sub>
420−</pre></td></tr></tbody></table>
497+ {% /table %}
422### `;=` Mictis
499### `;=` Mictis
@@ -426,23 +503,31 @@ of XML nodes) from a series of `$manx`es. This is mostly useful if you want to
426make the list outside of an element and then be able to insert it afterwards.
503make the list outside of an element and then be able to insert it afterwards.
427For example:
504For example:
429−<table><thead><tr><th>Sail</th><th>HTML</th></tr></thead><tbody><tr><td>
506+{% table %}
430−<pre class="language-hoon">
507+
431−=/ paras=marl
514+ =/ paras=marl
432− ;= ;p: First node.
515+ ;= ;p: First node.
433− ;p: Second node.
516+ ;p: Second node.
434− ;p: Third node.
517+ ;p: Third node.
440−&lt;main>
524+ <main>
441− &lt;p>First node.&lt;/p>
525+ <p>First node.</p>
442− &lt;p>Second node.&lt;/p>
526+ <p>Second node.</p>
443− &lt;p>Third node.&lt;/p>
527+ <p>Third node.</p>
444−&lt;/main>
528+ </main>
445−</pre></td></tr></tbody></table>
530+ {% /table %}
447### `;/` Micfas
532### `;/` Micfas