@@ -0,0 +1,616 @@
3+ title/'Urbit Markdown'
8+# Urbit Markdown: A Guide
11+### What is Urbit Markdown?
13+Urbit Markdown (UMD) is a way to write content for the web. It's a minimalist
14+markup language for creating and rendering text documents, with a
15+Markdown-inspired syntax. It's integrated with our Hoon programming language,
16+allowing it to be used as standalone prose in its own file or embedded inside a
17+Hoon source file, in which case it will be parsed into a tree of HTML nodes
18+using Hoon's XML-templating syntax, Sail.
21+This document is itself written in Urbit Markdown, and its source file is of the
22+Urbit Markdown `.umd` extension. As such, we use some `formatted text` to make
23+it clear what is and isn't code, and to display that code to you instead of
24+actually using its semantics for formatting.
26+There are quite a few similarities between Urbit Markdown and the
27+CommonMark standard, but there are enough differences that you shouldn't rely on
28+existing knowledge of the latter. Urbit Markdown generally supports only one
29+syntax for each type of HTML node it emits. Urbit Markdown is also stricter than
30+Markdown: some syntax errors will prevent the file from being parsed at all.
35+Before starting, make sure that your urbit is
36+[mounted to Unix](https://urbit.org/docs/using/setup/)
38+To host Urbit Markdown and other kinds of files, your ship also has a
39+web-server, called [Eyre](https://urbit.org/docs/using/web/), that can be found
40+at `http://localhost:8080/` if it’s your first ship that’s running on the
41+machine, `http://localhost:8081/` if it’s the second ship on that same machine,
42+and so on. If you can't find your ship on one of these for some reason, try the
45+That server has access to source files located in `/<your-urbit>/home/web` and
46+any sub-folders thereof (except for `/home/web/pages`, which has special
47+rendering rules.) Your ship's `%home` desk is served by default. You can
48+[change](https://urbit.org/docs/using/web/) which desk you're serving, however.
50+Everything in the `/<your-urbit>/home/web/` directory, with the exception of
51+`/home/web/pages`, knows how to interpret and files of `.umd` type. So, to
52+experiment with UM, create a `.umd` file in that path, and then try to access it
53+at `http://localhost:8080/<yourfile>` in your browser -- no `.umd` required in
54+the URL. It's a good idea to copy-paste the following examples into your file to
55+see how the code works.
57+Make sure that you have proper syntax throughout, and check often that it
58+renders properly as you add more code. If you have parser-breaking syntax, then
59+the default renderer won't tell you much.
65+The first thing on your file is a chunk of code called the front matter. It
66+contains metadata about your page, such as date, title, and position relative
69+As an example, let's look at the front matter of this very page:
72+:- :~ navhome/'/docs/'
74+ title/'Urbit Markdown'
81+`:-`, the Hoon rune for creating a cell, creates a cell composed of
82+the `:~` Hoon rune for creating a list, and `;>`, which is a Sail rune
85+`:~` creates a list out of the three elements: `navhome/'/docs/'`, which
86+indicates that navigating "home" will bring you to the urbit.org/docs section
87+of the website; `sort/'28',` which assigns it the 28th position of the
88+immediate section that contains it, the one you see in the sidebar;
89+and `title/'Urbit Markdown'`, which gives the page its title. The `==` digraph
92+`;>` is a Sail rune that creates a node that contains everything that follows
93+it, telling the parser that that text should be interpreted as Urbit Markdown.
94+It's not technically front matter, but you'll always find it following the
95+front matter, since all Urbit Markdown must come after this rune.
97+The categories listed in the example above -- `navhome`, `sort`, and `title` --
98+make sense to Eyre by default, but any arbitrary category can be used. The code
99+below is valid front matter.
102+:- :~ date/~2018.9.12
103+ author/~lodleb-ritrul
108+Note that `~2018.9.12`, `~lodleb-ritrul`, and `'rad'` are all of of atom
109+types: `@da`(date), `@p` (ship name), and `@t` (cord), respectively. Only atom
110+types work here. Having `music/"rad"` would prevent the source file from
115+Headers in Urbit Markdown begin the line with one or more `#` characters,
116+'followed by a single space. After that space comes the actual text to be
117+displayed. The number of leading `#`s corresponds to the resulting HTML
118+header-size element: `#` yields an `<h1>`, `##` yields an `<h2>`, and so on,
119+through `<h6>`. The header for this section is `### Headers`.
135+Enclosing text with `_` will cause that text to appear italicized, using an <i>
138+Enclosing text with `*` will cause that text to appear bolded, using a <b>
145+To get their *attention*, you need that _je ne sais quoi_.
150+To get their *attention*, you need that _je ne sais quoi_.
154+After a blank link is interpreted as a line break, creating a distinct
155+paragraph. However, a newline on its own is merely interpreted as a space on
161+Here's the first line.
163+This second line is separated by two newlines, so it's a separate paragraph.
165+This line looks like a distinct paragraph, but...
166+It's only separated by a single newline, so it's included in the same paragraph.
171+Here's the first line.
173+This second line is separated by two newlines, so it's a separate paragraph.
175+This line looks like a distinct paragraph, but...
176+It's only separated by a single newline, so it's included in the same paragraph.
178+#### Backslash Line Break
180+A backslash at the end of a line inserts a line break (`<br>`)
181+after that line. This contrasts with the normal udon behavior of
182+converting newlines to spaces.
186+I wonder how long each line
187+will be if I put backslashes\
188+at the ends of the lines.
192+I wonder how long each line
193+will be if I put backslashes\
194+at the ends of the lines.
198+A backslash directly _before_ a word (with no spaces) will be interpreted
199+as an escape character, causing it to be rendered raw.
204+Here is some *bold* text.
205+Here is some \*not bold* text.
210+Here is some *bold* text.
211+Here is some \*not bold* text.
216+A line beginning with a `-` followed by a space is interpreted as an
217+element of an *unordered list* (`<ul>`). Each line in an unordered list is
218+prepended with a bullet point.
220+A line beginning with a `+` followed by a space is interpreted as an element
221+of an *ordered list* (`<ol>`). Each line in an ordered list is prepended with
222+a number corresponding to its position in that list.
224+New list elements are delineated by newlines beginning with list symbols of
225+the appropriate type (`-` or `+`).
227+Just as with non-list text, text on a bare newline will appear on line before,
228+separated by a space. A `\\` is used to create a line-break that isn't the list
229+itself and isn't a list. Both of these kinds of newlines must be indented by two
230+spaces, or else the page will not parse.
232+Indentation is also used for creating nested sub-lists. Sub-lists of one kind
233+can be used with parent lists of the other kind. Sub-lists can't be nested
234+directly after either kind of aforementioned newline that isn't a list element;
235+only lines that are themselves list elements can nest sub-lists.
237+A newline after a blank line is interpreted as a new paragraph in normal text.
238+Between to list elements, however, a blank line is semantically equivalent to
239+a bare newline. To separate two lists with blank space, create a blank line
240+followed by a `\\` on its own line.
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
280+ Make sure that you get enough for the barbecue
282+ + Ask the baker what's fresh
283+ + Buy the second-freshest batch
287++ First, separate eggs into a bowl.
288++ Then, add a splash of cream.
289+ - If you don't have cream, you can use milk, but cream is preferred.
290+ + If you don't have milk or cream, melt an eighth of a stick of butter on
292+ + Scrambled the eggs in the bowl.
293+ + Pour the eggs onto the skillet before the butter browns
296++ Scramble eggs and put them into skillet
304+There are two ways to create links, but both contain the text be hyperlinked
305+in `[]` followed by the destination in `()`.
307+The first type is an inline-style link, which simply uses the full URL as its
313+[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)
318+[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)
320+The second type is a reference-style link, which uses a relative path, based on
321+the current page's location. Instead of the full url, we use `..` to fill in
322+the all of the URL that the destination has in common with the origin page.
327+[I'm a reference-style link](../library)
332+[I'm a reference-style link](../library)
334+If this page is located at `https://www.urbit.org/docs/hoon/`, then these two
335+examples should have the same destination.
339+A link to a section of the same page is in the style of
340+`[text to be linked](#the-destination)`.
342+The destination for the anchor link is designated with the HTML element `id`,
343+so we need to use some [Sail](#sail). If there are two or more anchors with
344+the same `id` on the page, you will arrive at the earliest instance of the the
350+Check out this [section](#the-destination) that we want to jump to.
352+Four score and seven years ago....
354+It was the best of times, it was the worst of times...
358+ ;div(id "the-destination"): Here we are!
365+Check out this [section](#the-destination) that we want to jump to.
367+Four score and seven years ago....
369+It was the best of times, it was the worst of times...
373+ ;div(id "the-destination"): Here we are!
379+Text enclosed in double quotes (`"`) will be rendered with
380+opening and closing quotes -- that is, `“` and `”`.
384+"Yes," he said. "That is the way with him."
389+"Yes," he said. "That is the way with him."
394+There are two ways to show the literal text of code without running it: inline
395+and block. Both highlight the contained text in another color.
397+Note that the backslash, due to its role as the escape character, can only be
398+displayed in a code block literal and not as inline code literal. This is a
405+##### Inline Code Literal
407+Enclosing some text in
411+characters will cause it to be displayed as code,
412+inside a `<code>` HTML element with monospace font and highlighted with a
413+different background color.
415+Using `` ` \`` is useful when you want to designated only part of a line as code.
416+Since this page is written in Urbit Markdown, we've been using this operation
417+throughout this guide to `format text` to distinguish code from prose.
421+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
425+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
427+Also, using the `++` prefix before a word will cause the word to be rendered as
428+code with the `++` displayed, since that's the standard notation for an arm in
434+The ++add arm is used to sum two numbers.
439+The ++add arm is used to sum two numbers.
441+#### Block Code Literal
443+By enclosing a block of text in ``` on their own lines
444+before and after the contained text, the text will be treated as a code block.
446+Most of our examples so far have used.
475+Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)
476+that can be used in udon as well. Urbit Markdown detects such code, and so these
477+forms will automatically appear inside a `<code>` element like inline code.
496+Three or more hyphens, such as `---`, on their own line produce an `<hr>`
497+element, the 'horizontal rule'. This is rendered as a horizontal line the
498+width of its containing paragraph.
507+And below this line, too
517+And below this line, too
521+A section of text with the first line beginning with `>` and a space,
522+and each successive newline indented by two spaces yields a
523+`<blockquote>` HTML element. This block quote can itself contain more Urbit
524+Markdown, including more block quotes to render nested levels of quotation.
525+Inline italicization with `_` does not work, however.
527+Blank newlines do not end the block quote, but a blank newline followed by an
528+unindented line of text _will_ end the quote.
533+> As Gregor Samsa awoke one morning from uneasy dreams, he
534+ found himself transformed in his bed into a *monstrous* vermin.
540+ He is pale and thin, he wears a thin and ragged linen shirt.
545+> As Gregor Samsa awoke one morning from uneasy dreams
546+ he found himself transformed in his bed into a *monstrous* vermin.
552+ He is pale and thin, he wears a thin and ragged linen shirt.
557+A poem is a section of text with meaningful newlines. Recall that,
558+normally in Urbit Markdown, newlines are treated as spaces and do not create a
559+new line of text. If you want to embed text where newlines are retained, then
560+indent the text in question with *eight spaces*.
565+ A shape with lion body and the head of a man,
566+ A gaze blank and pitiless as the sun,
567+ Is moving its slow thighs, while all about it
568+ Reel shadows of the indignant desert birds.
572+ A shape with lion body and the head of a man,
573+ A gaze blank and pitiless as the sun,
574+ Is moving its slow thighs, while all about it
575+ Reel shadows of the indignant desert birds.
580+ ;div(id "sail"): Sail Expressions
584+It's possible to use Urbit Markdown as an HTML templating language akin to
585+PHP, ERB, JSP, or Handlebars templates. This facility derives
586+in part from the support for embedding Hoon code inside the markup.
589+You can Sail is a domain-specific language within Hoon for creating XML nodes,
590+including HTML. It can be used directly within Urbit Markdown to provide
591+scripting capability with Hoon and also to provide more precise control over the
592+resulting HTML. The [Sail guide](../sail) is a good place to learn the
600+ ;strong: Don't panic!
602+ ;small: [reactive publishing intensifies]
612+ ;strong: Don't panic!
614+ ;small: [reactive publishing intensifies]