@@ -1,851 +0,0 @@
8−## <a name="udon"></a>Udon: A Guide
10−Udon is a way to write content for the web. It's a minimalist
11−markup language for creating and rendering text documents, with a
12−Markdown-inspired syntax. It's integrated with our Hoon programming language,
13−allowing it to be used as standalone prose in its own file or embedded inside a
14−Hoon source file, in which case it will be parsed into a tree of HTML nodes
15−using Hoon's XML-templating syntax, Sail.
17−This document is itself written in Udon, and its source file is of the
18−Udon `.udon` extension. As such, we use some `formatted text` to make
19−it clear what is and isn't code, and to display that code to you instead of
20−actually using its semantics for formatting.
22−There are quite a few similarities between Udon and the
23−CommonMark standard, but there are enough differences that you shouldn't rely on
24−existing knowledge of the latter. Udon generally supports only one
25−syntax for each type of HTML node it emits. Udon is also stricter than
26−Markdown: some syntax errors will prevent the file from being parsed at all.
28−We provide a few simple examples [here](#examples) of how to publish
29−Udon files using our web interface.
35−The first thing on your file is a chunk of code called the front matter. It
36−contains metadata about your page, such as date, title, and position relative
39−As an example, let's look at the front matter of this very page:
42−:- :~ navhome/'/docs/'
51−`:-`, the Hoon rune for creating a cell, creates a cell composed of
52−the `:~` Hoon rune for creating a list, and `;>`, which is a Sail rune
55−`:~` creates a list out of the three elements: `navhome/'/docs/'`, which
56−indicates that navigating "home" will bring you to the urbit.org/docs section
57−of the website; `sort/'28',` which assigns it the 28th position of the
58−immediate section that contains it, the one you see in the sidebar;
59−and `title/'Udon'`, which gives the page its title. The `==` digraph
62−`;>` is a Sail rune that creates a node that contains everything that follows
63−it, telling the parser that that text should be interpreted as Udon.
64−It's not technically front matter, but you'll always find it following the
65−front matter, since all Udon must come after this rune.
67−The categories listed in the example above -- `navhome`, `sort`, and `title` --
68−make sense to Eyre by default, but any arbitrary category can be used. The code
69−below is valid front matter.
73− author/~lodleb-ritrul
78−Note that `~2018.9.12`, `~lodleb-ritrul`, and `'rad'` are all of of atom
79−types: `@da`(date), `@p` (ship name), and `@t` (cord), respectively. Only atom
80−types work here. Having `music/"rad"` would prevent the source file from
85−Headers in Udon begin the line with one or more `#` characters,
86−'followed by a single space. After that space comes the actual text to be
87−displayed. The number of leading `#`s corresponds to the resulting HTML
88−header-size element: `#` yields an `<h1>`, `##` yields an `<h2>`, and so on,
89−through `<h6>`. The header for this section is `### Headers`.
105−Enclosing text with `_` will cause that text to appear italicized, using an `<i>`
108−Enclosing text with `*` will cause that text to appear bolded, using a `<b>`
115−To get their *attention*, you need that _je ne sais quoi_.
120−To get their **attention**, you need that _je ne sais quoi_.
124−A blank line is interpreted as a line break, creating a distinct
125−paragraph. However, a newline on its own is merely interpreted as a space on
131−Here's the first line.
133−This second line is separated by two newlines, so it's a separate paragraph.
135−This line looks like a distinct paragraph, but...
136−It's only separated by a single newline, so it's included in the same paragraph.
141−Here's the first line.
143−This second line is separated by two newlines, so it's a separate paragraph.
145−This line looks like a distinct paragraph, but...
146−It's only separated by a single newline, so it's included in the same paragraph.
148−#### Backslash Line Break
150−A backslash at the end of a line inserts a line break (`<br>`)
151−after that line. This contrasts with the normal udon behavior of
152−converting newlines to spaces.
156−I wonder how long each line
157−will be if I put backslashes\
158−at the ends of the lines.
162−I wonder how long each line
163−will be if I put backslashes\
164−at the ends of the lines.
168−A backslash directly _before_ a word (with no spaces) will be interpreted
169−as an escape character, causing it to be rendered raw.
174−Here is some *bold* text.
175−Here is some \*not bold* text.
180−Here is some **bold** text.
181−Here is some \*not bold* text.
186−A line beginning with a `-` followed by a space is interpreted as an
187−element of an **unordered list** (`<ul>`). Each line in an unordered list is
188−prepended with a bullet point.
190−A line beginning with a `+` followed by a space is interpreted as an element
191−of an **ordered list** (`<ol>`). Each line in an ordered list is prepended with
192−a number corresponding to its position in that list.
194−New list elements are delineated by newlines beginning with list symbols of
195−the appropriate type (`-` or `+`).
197−Just as with non-list text, text on a bare newline will appear on line before,
198−separated by a space. A `\\` is used to create a line-break that isn't the list
199−itself and isn't a list. Both of these kinds of newlines must be indented by two
200−spaces, or else the page will not parse.
202−Indentation is also used for creating nested sub-lists. Sub-lists of one kind
203−can be used with parent lists of the other kind. Sub-lists can't be nested
204−directly after either kind of aforementioned newline that isn't a list element;
205−only lines that are themselves list elements can nest sub-lists.
207−A newline after a blank line is interpreted as a new paragraph in normal text.
208−Between to list elements, however, a blank line is semantically equivalent to
209−a bare newline. To separate two lists with blank space, create a blank line
210−followed by a `\\` on its own line.
220− Make sure that you get enough for the barbecue
222− + Ask the baker what's fresh
223− + Buy the second-freshest batch
227−+ First, separate eggs into a bowl.
228−+ Then, add a splash of cream.
229− - If you don't have cream, you can use milk, but cream is preferred.
230− + If you don't have milk or cream, melt an eighth of a stick of butter on
232− + Scrambled the eggs in the bowl.
233− + Pour the eggs onto the skillet before the butter browns
236−+ Scramble eggs and put them into skillet
250− Make sure that you get enough for the barbecue
252− + Ask the baker what's fresh
253− + Buy the second-freshest batch
257−+ First, separate eggs into a bowl.
258−+ Then, add a splash of cream.
259− - If you don't have cream, you can use milk, but cream is preferred.
260− + If you don't have milk or cream, melt an eighth of a stick of butter on
262− + Scrambled the eggs in the bowl.
263− + Pour the eggs onto the skillet before the butter browns
266−+ Scramble eggs and put them into skillet
274−There are two ways to create links, but both contain the text be hyperlinked
275−in `[]` followed by the destination in `()`.
277−The first type is an inline-style link, which simply uses the full URL as its
283−[I'm an inline-style link](https://www.urbit.org/docs/reference/shell)
288−[I'm an inline-style link](https://www.urbit.org/docs/reference/shell)
290−The second type is a reference-style link, which uses a relative path, based on
291−the current page's location. Instead of the full url, we use `..` to fill in
292−the all of the URL that the destination has in common with the origin page.
297−[I'm a reference-style link](../shell)
302−[I'm a reference-style link](../shell)
304−If this page is located at `https://www.urbit.org/docs/reference/`, then these two
305−examples should have the same destination.
309−A link to a section of the same page is in the style of
310−`[text to be linked](#the-destination)`.
312−The destination for the anchor link is designated with the HTML element `id`,
313−so we need to use some [Sail](#sail). If there are two or more anchors with
314−the same `id` on the page, you will arrive at the earliest instance of the the
320−Check out this [section](#the-destination) that we want to jump to.
322−Four score and seven years ago....
324−It was the best of times, it was the worst of times...
331−Check out this [section](#the-destination) that we want to jump to.
333−Four score and seven years ago....
335−It was the best of times, it was the worst of times...
341−Text enclosed in double quotes (`"`) will be rendered with
342−opening and closing quotes -- that is, `“` and `”`.
346−"Yes," he said. "That is the way with him."
351−"Yes," he said. "That is the way with him."
356−There are two ways to show the literal text of code without running it: inline
357−and block. Both highlight the contained text in another color.
359−Note that the backslash, due to its role as the escape character, can only be
360−displayed in a code block literal and not as inline code literal. This is a
367−#### Inline Code Literal
369−Enclosing some text in
373−characters will cause it to be displayed as code,
374−inside a `<code>` HTML element with monospace font and highlighted with a
375−different background color.
377−Using `` ` \`` is useful when you want to designated only part of a line as code.
378−Since this page is written in Udon, we've been using this operation
379−throughout this guide to `format text` to distinguish code from prose.
383−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
387−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
389−Also, using the `++` prefix before a word will cause the word to be rendered as
390−code with the `++` displayed, since that's the standard notation for an arm in
396−The ++add arm is used to sum two numbers.
401−The ++add arm is used to sum two numbers.
403−#### Block Code Literal
405−By enclosing a block of text in a tick on their own lines
406−before and after the contained text, the text will be treated as a code block.
408−Most of our examples so far have used.
437−Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)
438−that can be used in udon as well. Udon detects such code, and so these
439−forms will automatically appear inside a `<code>` element like inline code.
458−Three or more hyphens, such as `---`, on their own line produce an `<hr>`
459−element, the 'horizontal rule'. This is rendered as a horizontal line the
460−width of its containing paragraph.
469−And below this line, too
479−And below this line, too
483−A section of text with the first line beginning with `>` and a space,
484−and each successive newline indented by two spaces yields a
485−`<blockquote>` HTML element. This block quote can itself contain more Udon,
486−including more block quotes to render nested levels of quotation.
487−Inline italicization with `_` does not work, however.
489−Blank newlines do not end the block quote, but a blank newline followed by an
490−unindented line of text _will_ end the quote.
495−> As Gregor Samsa awoke one morning from uneasy dreams, he
496− found himself transformed in his bed into a *monstrous* vermin.
502− He is pale and thin, he wears a thin and ragged linen shirt.
507−> As Gregor Samsa awoke one morning from uneasy dreams
508− he found himself transformed in his bed into a **monstrous** vermin.
514− He is pale and thin, he wears a thin and ragged linen shirt.
519−A poem is a section of text with meaningful newlines. Recall that,
520−normally in Udon, newlines are treated as spaces and do not create a
521−new line of text. If you want to embed text where newlines are retained, then
522−indent the text in question with **eight spaces**.
527− A shape with lion body and the head of a man,
528− A gaze blank and pitiless as the sun,
529− Is moving its slow thighs, while all about it
530− Reel shadows of the indignant desert birds.
534− A shape with lion body and the head of a man,
535− A gaze blank and pitiless as the sun,
536− Is moving its slow thighs, while all about it
537− Reel shadows of the indignant desert birds.
542−It's possible to use Udon as an HTML templating language akin to
543−PHP, ERB, JSP, or Handlebars templates. This facility derives
544−in part from the support for embedding Hoon code inside the markup.
547−Sail is a domain-specific language within Hoon for creating XML nodes,
548−including HTML. It can be used directly within Udon to provide
549−scripting capability with Hoon and also to provide more precise control over the
550−resulting HTML. The [Sail guide](../sail) is a good place to learn the
558− ;strong: Don't panic!
560− ;small: [reactive publishing intensifies]
569− <strong>Don't panic!</strong>
571− <small>[reactive publishing intensifies]</small>
575−## <a name="blog"></a>A Simple Udon Blog
577−Publishing using Udon is really easy. It uses the file extension `.udon`. Here we'll create a very simple blog and publish our first posts.
579−First, let's setup a desk to serve our posts from:
582−|merge %site ~your-urbit %home
585−Then let's mount that desk to unix:
591−You should now be able to find a `/site` folder inside of your pier
592−directory (either `comet/` or `your-urbit/`).
594−To begin serving files from this new desk use `|serve`:
600−First let's create the landing page for our blog. Create the file
601−`site/web/blog.udon`:
610−This is a simple blog I built on Urbit.
612−;list(dataType "post");
615−Try viewing this file at `http://localhost:8080`. Note that `8080` might be
616−`8081`, `8082`, and so on, depending if those ports were being used when you
619−The only special thing about this page is the `anchor/'none'` front-matter
620−which simply turns off the Tree navigation. Normally Tree gives navigation
621−controls for walking around the filesystem, but taking them away makes
622−the page seem more like a landing page.
624−The page looks pretty boring now. Let's add our first post. From
625−unix run `mkdir your-urbit/site/web/blog; touch
626−your-urbit/site/web/blog/post-1.udon`. (Currently [there's a
627−bug](https://github.com/urbit/urbit/issues/321) that prevents empty
628−directories from getting created, so we have to `touch` a file inside
629−them first.) In `blog/post-1.udon` let's add some filler content:
632−:- :~ navhome/'/blog'
635− title/'My first post!'
639−Is this a decentralized Medium? Let's find out.
641−But first, how about a long quote from Paramenides:
643−> True, he said; and therefore when ideas are what they are in
644− relation to one another, their essence is determined by a relation
645− among themselves, and has nothing to do with the resemblances, or
646− whatever they are to be termed, which are in our sphere, and from
647− which we receive this or that name when we partake of them. And
648− the things which are within our sphere and have the same names
649− with them, are likewise only relative to one another, and not to
650− the ideas which have the same names with them, but belong to
651− themselves and not to them.
653−Good to get that out of the way.
656−You should be able to view this file at:
657−`http://localhost:8080/blog/post-1.udon`.
659−You'll also notice that
660−now the list of posts here: `http://localhost:8080/blog` has
663−Here we use two pieces of front-matter worth noting: `type` and `navhome`.
665−- `type` implies that the page has some special handling by Tree. When `type` is
666− `post` we automatically put in the `date`, `title` and `author` when they're
667− specified and add some styles.
669−- `navhome` sets the path used by the home button (the circle in the top left).
670− Since we want to send people back to the root of our blog, we set this to `/blog`
672−Adding posts is as easy as dropping Udon files into the `blog/`
673−directory. Pretty easy!
677−Now let's enable comments on a blog post.
679−First, turn comments on by editing the frontmatter in `post-1.udon`. Your
680−frontmatter should look like this:
683−:- :~ navhome/'/blog'
686− title/'Blog comments'
692−Now try loading your post here: `your-urbit.urbit.org/blog/post-1`.
693−You should see a comments box at the bottom of the page.
695−Try posting a comment! When you do you should see the following in
699−+ /~your-urbit/home/55/web/blog/post-1/comments/~2016.6.20..23.20.54..0b88/md
701−~your-urbit[tree]: receiving comments, ;join %comments for details
704−Comments are written into the filesystem in the `comments/` folder
705−relative to the page they're enabled on. When a new comment is posted
706−a notification is also posted to the `/comments` `:talk` channel.
708−Use `;join` to keep up with comments as they get posted:
711−;join ~your-urbit/comments
716−## <a name="static"></a>A Static Site
718−Hosting a static tree of content is easy. Let's put together a really
719−simple site for an imaginary Urbit meetup group.
721−We assume you have at least followed the beginning of [our first
722−examples](#blog) and created a desk called `site` and mounted it to
725−Note: below we use Urbit's implementation of Markdown, [Udon](#udon).
726−This markup language allows you to use snippets of Hoon code but not HTML.
727−In particular, we use Sail, a subset of Hoon. This Sail is rendered as HTML
728−when the file is served to a client. To learn about Sail, head over to
729−the [Sail](/docs/learn/arvo/arvo-internals/sail) section of the docs.
731−In `site/web/meet.udon` put:
734−:- :~ navhome/'/meet'
741−# Neo-Tokyo Urbit meetup
743−
745−Hi there! We meet once a week at The Chat to work on Urbit projects
748−You can find out more about the group on the [about](about) page and
749−follow our projects in [projects](projects).
752−This is our landing page. Here we're using a few new bits of frontmatter:
753−`navdpad`, `navmode` and `navpath`. `navdpad` just turns off the nav
754−arrows. `navmode` can be set to 'navbar' to switch to a horizontal top
755−nav instead of a left bar. `navpath` sets the path to load the nav
758−Let's create `about.udon` and `projects.udon`. From Unix use the
759−technique from before to create a new directory: `mkdir
760−your-urbit/site/web/meet/; touch your-urbit/site/web/meet/about.udon`.
761−Then put the following in `site/web/about.udon`:
764−:- :~ navhome/'/meet'
776−The existing framework cannot subdue the new human force that is increasing day
777−by day alongside the irresistible development of technology and the
778−dissatisfaction of its possible uses in our senseless social life.
782−Membership is open to anyone. Just send a message to `~talsur-todres`.
791−And `site/web/projects.udon`:
794−:- :~ navhome/'/meet'
810−;div(class "mini-module")
811− ;script(src "/~/at/lib/js/urb.js");
812− ;script(src "https://cdn.rawgit.com/seatgeek/react-infinite/0.8.0/dist/react-infinite.js");
813− ;script(src "https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.11.2/moment-with-locales.js");
814− ;script(src "https://cdnjs.cloudflare.com/ajax/libs/moment-timezone/0.5.1/moment-timezone.js");
815− ;script(src "/talk/main.js");
816− ;link(href "/talk/main.css", rel "stylesheet");
817− ;talk(readonly "", chrono="reverse", station="comments");
821−This page introduces a new thing: the `:talk` module. Inside of the
822−`mini-module` div we load the scripts needed by the `;talk`
823−component. The `;talk` component is a static component for
824−displaying a feed from a talk channel inline. Here we're going to
825−display the discussion from our active projects inline.
827−We'll need a few active projects though. From unix: `mkdir
828−your-urbit/site/web/meet/projects; touch
829−your-urbit/site/web/meet/projects/bike.udon`.
831−In `site/web/meet/projects/bike.udon`:
834−:- :~ navhome/'/meet'
838− title/'Kaneda's Bike'
843−# Urbit on a Motorcycle
845−Discussion on getting urbit to power Kaneda's motorcycle.
848−Here we just use the `comments` frontmatter to enable comments on the page.
849−Adding other imaginary projects is left to the reader.
851−Building a static site takes only a few minutes and a few Udon files. Have fun!