12Udon is a way to write content for the web. It's a minimalist
13markup language for creating and rendering text documents, with a
14Markdown-inspired syntax. It's integrated with our Hoon programming language,
15allowing it to be used as standalone prose in its own file or embedded inside a
16Hoon source file, in which case it will be parsed into a tree of HTML nodes
17using Hoon's XML-templating syntax, Sail.
19This document is itself written in Udon, and its source file is of the
20Udon `.udon` extension. As such, we use some `formatted text` to make
21it clear what is and isn't code, and to display that code to you instead of
22actually using its semantics for formatting.
24There are quite a few similarities between Udon and the
25CommonMark standard, but there are enough differences that you shouldn't rely on
26existing knowledge of the latter. Udon generally supports only one
27syntax for each type of HTML node it emits. Udon is also stricter than
28Markdown: some syntax errors will prevent the file from being parsed at all.
30We provide a few simple examples [here](#examples) of how to publish
31Udon files using our web interface.
36Before starting, make sure that your urbit is
37[mounted to Unix](https://urbit.org/docs/using/setup/)
39To host Udon and other kinds of files, your ship also has a
40web-server, called [Eyre](https://urbit.org/docs/using/web/), that can be found
41at `http://localhost:8080/` if it’s your first ship that’s running on the
42machine, `http://localhost:8081/` if it’s the second ship on that same machine,
43and so on. If you can't find your ship on one of these for some reason, try the
44next one. When a ship starts, it will print a message like
45`http: live (insecure, public) on 8081` to let you know what port it's using.
47That server has access to source files located in `/<your-urbit>/home/web` and
48any sub-folders thereof (except for `/home/web/pages`, which has special
49rendering rules.) Your ship's `%home` desk is served by default. You can
50[change](https://urbit.org/docs/using/web/) which desk you're serving, however.
52Everything in the `/<your-urbit>/home/web/` directory, with the exception of
53`/home/web/pages`, knows how to interpret and files of `.udon` type. So, to
54experiment with UM, create a `.udon` file in that path, and then try to access it
55at `http://localhost:8080/<yourfile>` in your browser -- no `.udon` required in
56the URL. It's a good idea to copy-paste the following examples into your file to
57see how the code works.
59Make sure that you have proper syntax throughout, and check often that it
60renders properly as you add more code. If you have parser-breaking syntax, then
61the default renderer won't tell you much.
67The first thing on your file is a chunk of code called the front matter. It
68contains metadata about your page, such as date, title, and position relative
71As an example, let's look at the front matter of this very page:
83`:-`, the Hoon rune for creating a cell, creates a cell composed of
84the `:~` Hoon rune for creating a list, and `;>`, which is a Sail rune
87`:~` creates a list out of the three elements: `navhome/'/docs/'`, which
88indicates that navigating "home" will bring you to the urbit.org/docs section
89of the website; `sort/'28',` which assigns it the 28th position of the
90immediate section that contains it, the one you see in the sidebar;
91and `title/'Udon'`, which gives the page its title. The `==` digraph
94`;>` is a Sail rune that creates a node that contains everything that follows
95it, telling the parser that that text should be interpreted as Udon.
96It's not technically front matter, but you'll always find it following the
97front matter, since all Udon must come after this rune.
99The categories listed in the example above -- `navhome`, `sort`, and `title` --
100make sense to Eyre by default, but any arbitrary category can be used. The code
101below is valid front matter.
105 author/~lodleb-ritrul
110Note that `~2018.9.12`, `~lodleb-ritrul`, and `'rad'` are all of of atom
111types: `@da`(date), `@p` (ship name), and `@t` (cord), respectively. Only atom
112types work here. Having `music/"rad"` would prevent the source file from
117Headers in Udon begin the line with one or more `#` characters,
118'followed by a single space. After that space comes the actual text to be
119displayed. The number of leading `#`s corresponds to the resulting HTML
120header-size element: `#` yields an `<h1>`, `##` yields an `<h2>`, and so on,
121through `<h6>`. The header for this section is `### Headers`.
137Enclosing text with `_` will cause that text to appear italicized, using an <i>
140Enclosing text with `*` will cause that text to appear bolded, using a <b>
147To get their *attention*, you need that _je ne sais quoi_.
152To get their *attention*, you need that _je ne sais quoi_.
156After a blank link is interpreted as a line break, creating a distinct
157paragraph. However, a newline on its own is merely interpreted as a space on
163Here's the first line.
165This second line is separated by two newlines, so it's a separate paragraph.
167This line looks like a distinct paragraph, but...
168It's only separated by a single newline, so it's included in the same paragraph.
173Here's the first line.
175This second line is separated by two newlines, so it's a separate paragraph.
177This line looks like a distinct paragraph, but...
178It's only separated by a single newline, so it's included in the same paragraph.
180#### Backslash Line Break
182A backslash at the end of a line inserts a line break (`<br>`)
183after that line. This contrasts with the normal udon behavior of
184converting newlines to spaces.
188I wonder how long each line
189will be if I put backslashes\
190at the ends of the lines.
194I wonder how long each line
195will be if I put backslashes\
196at the ends of the lines.
200A backslash directly _before_ a word (with no spaces) will be interpreted
201as an escape character, causing it to be rendered raw.
206Here is some *bold* text.
207Here is some \*not bold* text.
212Here is some *bold* text.
213Here is some \*not bold* text.
218A line beginning with a `-` followed by a space is interpreted as an
219element of an *unordered list* (`<ul>`). Each line in an unordered list is
220prepended with a bullet point.
222A line beginning with a `+` followed by a space is interpreted as an element
223of an *ordered list* (`<ol>`). Each line in an ordered list is prepended with
224a number corresponding to its position in that list.
226New list elements are delineated by newlines beginning with list symbols of
227the appropriate type (`-` or `+`).
229Just as with non-list text, text on a bare newline will appear on line before,
230separated by a space. A `\\` is used to create a line-break that isn't the list
231itself and isn't a list. Both of these kinds of newlines must be indented by two
232spaces, or else the page will not parse.
234Indentation is also used for creating nested sub-lists. Sub-lists of one kind
235can be used with parent lists of the other kind. Sub-lists can't be nested
236directly after either kind of aforementioned newline that isn't a list element;
237only lines that are themselves list elements can nest sub-lists.
239A newline after a blank line is interpreted as a new paragraph in normal text.
240Between to list elements, however, a blank line is semantically equivalent to
241a bare newline. To separate two lists with blank space, create a blank line
242followed by a `\\` on its own line.
252 Make sure that you get enough for the barbecue
254 + Ask the baker what's fresh
255 + Buy the second-freshest batch
259+ First, separate eggs into a bowl.
260+ Then, add a splash of cream.
261 - If you don't have cream, you can use milk, but cream is preferred.
262 + If you don't have milk or cream, melt an eighth of a stick of butter on
264 + Scrambled the eggs in the bowl.
265 + Pour the eggs onto the skillet before the butter browns
268+ Scramble eggs and put them into skillet
282 Make sure that you get enough for the barbecue
284 + Ask the baker what's fresh
285 + Buy the second-freshest batch
289+ First, separate eggs into a bowl.
290+ Then, add a splash of cream.
291 - If you don't have cream, you can use milk, but cream is preferred.
292 + If you don't have milk or cream, melt an eighth of a stick of butter on
294 + Scrambled the eggs in the bowl.
295 + Pour the eggs onto the skillet before the butter browns
298+ Scramble eggs and put them into skillet
306There are two ways to create links, but both contain the text be hyperlinked
307in `[]` followed by the destination in `()`.
309The first type is an inline-style link, which simply uses the full URL as its
315[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)
320[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)
322The second type is a reference-style link, which uses a relative path, based on
323the current page's location. Instead of the full url, we use `..` to fill in
324the all of the URL that the destination has in common with the origin page.
329[I'm a reference-style link](../library)
334[I'm a reference-style link](../library)
336If this page is located at `https://www.urbit.org/docs/hoon/`, then these two
337examples should have the same destination.
341A link to a section of the same page is in the style of
342`[text to be linked](#the-destination)`.
344The destination for the anchor link is designated with the HTML element `id`,
345so we need to use some [Sail](#sail). If there are two or more anchors with
346the same `id` on the page, you will arrive at the earliest instance of the the
352Check out this [section](#the-destination) that we want to jump to.
354Four score and seven years ago....
356It was the best of times, it was the worst of times...
360 ;div(id "the-destination"): Here we are!
367Check out this [section](#the-destination) that we want to jump to.
369Four score and seven years ago....
371It was the best of times, it was the worst of times...
375 ;div(id "the-destination"): Here we are!
381Text enclosed in double quotes (`"`) will be rendered with
382opening and closing quotes -- that is, `“` and `”`.
386"Yes," he said. "That is the way with him."
391"Yes," he said. "That is the way with him."
396There are two ways to show the literal text of code without running it: inline
397and block. Both highlight the contained text in another color.
399Note that the backslash, due to its role as the escape character, can only be
400displayed in a code block literal and not as inline code literal. This is a
407##### Inline Code Literal
409Enclosing some text in
413characters will cause it to be displayed as code,
414inside a `<code>` HTML element with monospace font and highlighted with a
415different background color.
417Using `` ` \`` is useful when you want to designated only part of a line as code.
418Since this page is written in Udon, we've been using this operation
419throughout this guide to `format text` to distinguish code from prose.
423`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
427`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
429Also, using the `++` prefix before a word will cause the word to be rendered as
430code with the `++` displayed, since that's the standard notation for an arm in
436The ++add arm is used to sum two numbers.
441The ++add arm is used to sum two numbers.
443#### Block Code Literal
445By enclosing a block of text in ``` on their own lines
446before and after the contained text, the text will be treated as a code block.
448Most of our examples so far have used.
477Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)
478that can be used in udon as well. Udon detects such code, and so these
479forms will automatically appear inside a `<code>` element like inline code.
498Three or more hyphens, such as `---`, on their own line produce an `<hr>`
499element, the 'horizontal rule'. This is rendered as a horizontal line the
500width of its containing paragraph.
509And below this line, too
519And below this line, too
523A section of text with the first line beginning with `>` and a space,
524and each successive newline indented by two spaces yields a
525`<blockquote>` HTML element. This block quote can itself contain more Udon,
526including more block quotes to render nested levels of quotation.
527Inline italicization with `_` does not work, however.
529Blank newlines do not end the block quote, but a blank newline followed by an
530unindented line of text _will_ end the quote.
535> As Gregor Samsa awoke one morning from uneasy dreams, he
536 found himself transformed in his bed into a *monstrous* vermin.
542 He is pale and thin, he wears a thin and ragged linen shirt.
547> As Gregor Samsa awoke one morning from uneasy dreams
548 he found himself transformed in his bed into a *monstrous* vermin.
554 He is pale and thin, he wears a thin and ragged linen shirt.
559A poem is a section of text with meaningful newlines. Recall that,
560normally in Udon, newlines are treated as spaces and do not create a
561new line of text. If you want to embed text where newlines are retained, then
562indent the text in question with *eight spaces*.
567 A shape with lion body and the head of a man,
568 A gaze blank and pitiless as the sun,
569 Is moving its slow thighs, while all about it
570 Reel shadows of the indignant desert birds.
574 A shape with lion body and the head of a man,
575 A gaze blank and pitiless as the sun,
576 Is moving its slow thighs, while all about it
577 Reel shadows of the indignant desert birds.
582 ;div(id "sail"): Sail Expressions
586It's possible to use Udon as an HTML templating language akin to
587PHP, ERB, JSP, or Handlebars templates. This facility derives
588in part from the support for embedding Hoon code inside the markup.
591You can Sail is a domain-specific language within Hoon for creating XML nodes,
592including HTML. It can be used directly within Udon to provide
593scripting capability with Hoon and also to provide more precise control over the
594resulting HTML. The [Sail guide](../sail) is a good place to learn the
602 ;strong: Don't panic!
604 ;small: [reactive publishing intensifies]
614 ;strong: Don't panic!
616 ;small: [reactive publishing intensifies]
620 ;div(id "examples"): Examples
623We've created a few simple examples of how to get set up publishing content from
624your Urbit. Feel free to ask questions in the comments.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list