# Sail (HTML) Sail is a domain-specific language for composing HTML (and XML) structures in Hoon. Like everything else in Hoon, a Sail document is a noun, just one produced by a specialized markup language within Hoon. Front-ends for Urbit apps are often created and uploaded separately to the rest of the code in the desk. Sail provides an alternative approach, where front-ends can be composed directly inside agents. This document will walk through the basics of Sail and its syntax. ## Basic example It’s easy to see how Sail can directly translate to HTML: {% tabs %} {% tab title="Sail" %} ```hoon ;html ;head ;title = My page ;meta(charset "utf-8"); == ;body ;h1: Welcome! ;p ; Hello, world! ; Welcome to my page. ; Here is an image: ;br; ;img@"/foo.png"; == == == ``` {% endtab %} {% tab title="HTML" %} ```html My page

Welcome!

Hello, world! Welcome to my page. Here is an image:

``` {% endtab %} {% endtabs %} ## Tags and Closing In Sail, tag heads are written with the tag name prepended by `;`. Unlike in HTML, there are different ways of closing tags, depending on the needs of the tag. One of the nice things about Hoon is that you don’t have to constantly close expressions; Sail inherits this convenience. ### Empty Empty tags are closed with a `;` following the tag. For example, `;div;` will be rendered as `

`. Non-container tags `;br;` and `;img@"some-url";` in particular will be rendered as a single tag like `
` and `

`. ### Filled Filled tags are closed via line-break. To fill text inside, add `:` after the tag name, then insert your plain text following a space. Example: | Sail | HTML | | ---------------- | -------------------- | | `;h1: The title` | `

The title

` | ### Nested To nest tags, simply create a new line. Nested tags need to be closed with `==`, because they expect a list of sub-tags. If we nest lines of plain text with no tag, the text will be wrapped in a `

` tag. Additionally, any text with atom auras or `+arm:syntax` in such plain text lines will be wrapped in `` tags. Example: {% tabs %} {% tab title="Sail" %} ```hoon ;body ;h1: Blog title This is some good content. == ``` {% endtab %} {% tab title="HTML" %} ```

`Blog title`


This is some good content.

```

{% endtab %}
{% endtabs %}

If we want to write a string with no tag at all, then we can prepend those untagged lines with `;` and then a space:

{% tabs %}
{% tab title="Sail" %}

```hoon
;body
  ;h1: Welcome!
  ; Hello, world!
  ; We’re on the web.
==
```

{% endtab %}

{% tab title="HTML" %}

```html

  Welcome!
  Hello, world!
  We’re on the web.

```

{% endtab %}
{% endtabs %}

## Attributes 

Adding attributes is simple: just add the desired attribute between parentheses, right after the tag name without a space. We separate different attributes of the same node by using `,`.

Attributes can also be specified in tall form, with each key prefixed by `=`, followed by two spaces, and then a tape with its value. These two styles are shown below.

### Generic 

{% tabs %}
{% tab title="Wide" %}

```hoon
;div(title "a tooltip", style "color:red")
  ;h1: Foo
  foo bar baz
==
```

{% endtab %}

{% tab title="Tall" %}

```hoon
;div
  =title  "a tooltip"
  =style  "color:red"
  ;h1: Foo
  foo bar baz
==
```

{% endtab %}

{% tab title="HTML" %}

```

  Foo
  foo bar baz 

```

{% endtab %}
{% endtabs %}

### IDs 

Add `#` after tag name to add an ID:

| Sail                | HTML                          |
| ------------------- | ----------------------------- |
| `;nav#header: Menu` | `Menu` |

### Classes 

Add `.` after tag name to add a class:

| Sail                   | HTML                               |
| ---------------------- | ---------------------------------- |
| `;h1.text-blue: Title` | `Title` |

For class values containing spaces, you can add additional `.`s like so:

| Sail                | HTML                              |
| ------------------- | --------------------------------- |
| `;div.foo.bar.baz;` | `` |

Otherwise, if your class value does not conform to the allowed `@tas` characters, you must use the generic attribute syntax:

| Sail                     | HTML                          |
| ------------------------ | ----------------------------- |
| `;div(class "!!! !!!");` | `` |

### Images 

Add `@` after the tag name to link your source:

| Sail                  | HTML                       |
| --------------------- | -------------------------- |
| `;img@"example.png";` | `` |

To add attributes to the image, like size specifications, add the desired attribute after the `"` of the image name and before the final `;` of the `img` tag like `;img@"example.png"(width "100%");`.

### Links 

Add `/` after tag name to start an `href`.

{% tabs %}
{% tab title="Sail" %}

```hoon
;a/"urbit.org": A link to Urbit.org
```

{% endtab %}

{% tab title="HTML" %}

```html
A link to Urbit.org
```

{% endtab %}
{% endtabs %}

## Interpolation 

The textual content of tags, despite not being enclosed in double-quotes, are actually tapes. This means they support interpolated Hoon expressions in the usual manner. For example:

{% tabs %}
{% tab title="Sail" %}

```hoon
=|  =time
;p: foo {} bar
```

{% endtab %}

{% tab title="HTML" %}

```html
foo ~2000.1.1 baz
```

{% endtab %}
{% endtabs %}

Likewise:

{% tabs %}
{% tab title="Sail" %}

```hoon
=/  txt=tape  " bananas"
;article
  ;b: {(a-co:co (mul 42 789))}
  ; {txt}
  {} {} {<`@ux`(end 6 eny)>}
==
```

{% endtab %}

{% tab title="HTML" %}

```html

  33138 bananas
  ~zod ~2022.2.21..09.54.21..5b63 0x9827.99c7.06f4.8ef9

```

{% endtab %}
{% endtabs %}

## A note on CSS 

The CSS for a page is usually quite large. The typical approach is to include a separate arm in your agent (`+style` or the like) and write out the CSS in a fenced cord block. You can then call `+trip` on it and include it in a style tag. For example:

```hoon
++  style
  ^~
  %-  trip
  '''
  main {
    width: 100%;
    color: red;
  }
  header {
    color: blue;
    font-family: monospace;
  }
  '''
```

And then your style tag might look like:

```hoon
;style: {style}
```

A cord is used rather than a tape so you don't need to escape braces. The [ketsig](https://docs.urbit.org/rune/ket#ketsig) (`^~`) rune means `+trip` will be run at compile time rather than call time.

## Types and marks 

So far we've shown rendered HTML for demonstrative purposes, but Sail syntax doesn't directly produce HTML text. Instead, it produces a [$manx](https://docs.urbit.org/stdlib/5e#manx). This is a Hoon type used to represent an XML hierarchical structure with a single root node. There are six XML-related types defined in the standard library:

```hoon
+$  mane  $@(@tas [@tas @tas])                    ::  XML name+space
+$  manx  $~([[%$ ~] ~] [g=marx c=marl])          ::  dynamic XML node
+$  marl  (list manx)                             ::  XML node list
+$  mars  [t=[n=%$ a=[i=[n=%$ v=tape] t=~]] c=~]  ::  XML cdata
+$  mart  (list [n=mane v=tape])                  ::  XML attributes
+$  marx  $~([%$ ~] [n=mane a=mart])              ::  dynamic XML tag
```

More information about these can be found in [section 5e of the standard library reference](https://docs.urbit.org/hoon/stdlib/5e).

You don't need to understand these types in order to write Sail. The main thing to note is that a `$manx` is a node (a single tag) and its contents is a [$marl](https://docs.urbit.org/stdlib/5e#marl), which is just a `(list manx)`.

### Rendering 

A `$manx` can be rendered as HTML in a tape with the `+en-xml:html` function in `zuse.hoon`. For example:

```
> ;p: foobar
[[%p ~] [[%$ [%$ "foobar"] ~] ~] ~]

> =x ;p: foobar

> (en-xml:html x)
"foobar"

> (crip (en-xml:html x))
'foobar'
```

### Sanitization 

The `+en-xml:html` function will sanitize the contents of both attributes and elements, converting characters such as `>` to HTML entities. For example:

```
> =z ;p(class "\">