@@ -0,0 +1,616 @@
1+:- :~ navhome/'/docs/'
2+ sort/'11'
3+ title/'Urbit Markdown'
4+ ==
5+
6+;>
7+
8+# Urbit Markdown: A Guide
9+
10+
11+### What is Urbit Markdown?
12+
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.
19+
20+
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.
25+
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.
31+
32+
33+### Getting Started
34+
35+Before starting, make sure that your urbit is
36+[mounted to Unix](https://urbit.org/docs/using/setup/)
37+
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
43+next one.
44+
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.
49+
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.
56+
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.
60+
61+## Syntax
62+
63+### Front Matter
64+
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
67+to sibling pages.
68+
69+As an example, let's look at the front matter of this very page:
70+
71+```
72+:- :~ navhome/'/docs/'
73+ sort/'11'
74+ title/'Urbit Markdown'
75+ ==
76+;>
77+```
78+
79+What's going on here?
80+
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
83+for Urbit Markdown.
84+
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
90+terminates the list.
91+
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.
96+
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.
100+
101+```
102+:- :~ date/~2018.9.12
103+ author/~lodleb-ritrul
104+ music/'rad'
105+ ==
106+```
107+
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
111+parsing.
112+
113+### Headers
114+
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`.
120+
121+*Example:*
122+```
123+#### Header (h4)
124+
125+##### Header (h5)
126+```
127+###### Produces:
128+
129+#### Header (h4)
130+
131+##### Header (h5)
132+
133+### Italics and Bold
134+
135+Enclosing text with `_` will cause that text to appear italicized, using an <i>
136+element.
137+
138+Enclosing text with `*` will cause that text to appear bolded, using a <b>
139+element.
140+
141+
142+*Example:*
143+
144+```
145+To get their *attention*, you need that _je ne sais quoi_.
146+```
147+
148+###### Produces:
149+
150+To get their *attention*, you need that _je ne sais quoi_.
151+
152+### Line Break
153+
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
156+the _same line_.
157+
158+*Example:*
159+
160+```
161+Here's the first line.
162+
163+This second line is separated by two newlines, so it's a separate paragraph.
164+
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.
167+```
168+###### Produces:
169+
170+
171+Here's the first line.
172+
173+This second line is separated by two newlines, so it's a separate paragraph.
174+
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.
177+
178+#### Backslash Line Break
179+
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.
183+
184+*Example:*
185+```
186+I wonder how long each line
187+will be if I put backslashes\
188+at the ends of the lines.
189+```
190+###### Produces:
191+
192+I wonder how long each line
193+will be if I put backslashes\
194+at the ends of the lines.
195+
196+### Escape
197+
198+A backslash directly _before_ a word (with no spaces) will be interpreted
199+as an escape character, causing it to be rendered raw.
200+
201+*Example:*
202+
203+```
204+Here is some *bold* text.
205+Here is some \*not bold* text.
206+```
207+
208+###### Produces:
209+
210+Here is some *bold* text.
211+Here is some \*not bold* text.
212+
213+
214+### List
215+
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.
219+
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.
223+
224+New list elements are delineated by newlines beginning with list symbols of
225+the appropriate type (`-` or `+`).
226+
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.
231+
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.
236+
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.
241+
242+*Example:*
243+
244+```
245+- Eggs
246+ (cage-free)
247+- Milk
248+- Butter
249+- Chicken\
250+ Make sure that you get enough for the barbecue
251+- Bread
252+ + Ask the baker what's fresh
253+ + Buy the second-freshest batch
254+- Cereal
255+
256+\
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
261+ a skillet
262+ + Scrambled the eggs in the bowl.
263+ + Pour the eggs onto the skillet before the butter browns
264++ Heat the skillet
265+
266++ Scramble eggs and put them into skillet
267+
268+\
269++ Cool
270++ Alright
271+```
272+
273+Produces
274+
275+- Eggs
276+ (cage-free)
277+- Milk
278+- Butter
279+- Chicken\
280+ Make sure that you get enough for the barbecue
281+- Bread
282+ + Ask the baker what's fresh
283+ + Buy the second-freshest batch
284+- Cereal
285+
286+\
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
291+ a skillet
292+ + Scrambled the eggs in the bowl.
293+ + Pour the eggs onto the skillet before the butter browns
294++ Heat the skillet
295+
296++ Scramble eggs and put them into skillet
297+
298+\
299++ Cool
300++ Alright
301+
302+### Link
303+
304+There are two ways to create links, but both contain the text be hyperlinked
305+in `[]` followed by the destination in `()`.
306+
307+The first type is an inline-style link, which simply uses the full URL as its
308+destination.
309+
310+*Example:*
311+
312+```
313+[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)
314+```
315+
316+###### Produces:
317+
318+[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)
319+
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.
323+
324+*Example:*
325+
326+```
327+[I'm a reference-style link](../library)
328+```
329+
330+###### Produces:
331+
332+[I'm a reference-style link](../library)
333+
334+If this page is located at `https://www.urbit.org/docs/hoon/`, then these two
335+examples should have the same destination.
336+
337+#### Anchor Link
338+
339+A link to a section of the same page is in the style of
340+`[text to be linked](#the-destination)`.
341+
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
345+anchor.
346+
347+###### Example:
348+
349+```
350+Check out this [section](#the-destination) that we want to jump to.
351+
352+Four score and seven years ago....
353+
354+It was the best of times, it was the worst of times...
355+
356+;=
357+ ;h2
358+ ;div(id "the-destination"): Here we are!
359+ ==
360+==
361+```
362+
363+###### Produces
364+
365+Check out this [section](#the-destination) that we want to jump to.
366+
367+Four score and seven years ago....
368+
369+It was the best of times, it was the worst of times...
370+
371+;=
372+ ;h2
373+ ;div(id "the-destination"): Here we are!
374+ ==
375+==
376+
377+### Double Quote
378+
379+Text enclosed in double quotes (`"`) will be rendered with
380+opening and closing quotes -- that is, `“` and `”`.
381+
382+*Example:*
383+```
384+"Yes," he said. "That is the way with him."
385+```
386+
387+###### Produces:
388+
389+"Yes," he said. "That is the way with him."
390+
391+
392+### Code Literal
393+
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.
396+
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
399+bug.
400+
401+```
402+\
403+```
404+
405+##### Inline Code Literal
406+
407+Enclosing some text in
408+```
409+`
410+```
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.
414+
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.
418+
419+*Example:*
420+```
421+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
422+```
423+###### Produces:
424+
425+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
426+
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
429+Hoon.
430+
431+*Example:*
432+
433+```
434+The ++add arm is used to sum two numbers.
435+```
436+
437+###### Produces:
438+
439+The ++add arm is used to sum two numbers.
440+
441+#### Block Code Literal
442+
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.
445+
446+Most of our examples so far have used.
447+
448+*Example:*
449+
450+
451+```
452+ ```
453+ (def Y (fn [f]
454+ ((fn [x]
455+ (x x))
456+ (fn [x]
457+ (f (fn [y]
458+ ((x x) y)))))))
459+ ```
460+```
461+
462+###### Produces:
463+
464+```
465+(def Y (fn [f]
466+ ((fn [x]
467+ (x x))
468+ (fn [x]
469+ (f (fn [y]
470+ ((x x) y)))))))
471+```
472+
473+### Hoon Constants
474+
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.
478+
479+Example:
480+
481+```
482+~2017.8.29 \
483+0xdead.beef \
484+%term
485+```
486+
487+produces:\
488+
489+~2017.8.29 \
490+0xdead.beef \
491+%term
492+
493+
494+### Horizontal Rule
495+
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.
499+
500+###### Example:
501+
502+```
503+Above the line
504+---
505+Below the line
506+-----
507+And below this line, too
508+```
509+
510+###### Produces:
511+
512+
513+Above the line
514+---
515+Below the line
516+-----
517+And below this line, too
518+
519+### Block Quote
520+
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.
526+
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.
529+
530+*Example:*
531+
532+```
533+> As Gregor Samsa awoke one morning from uneasy dreams, he
534+ found himself transformed in his bed into a *monstrous* vermin.
535+
536+Quote break.
537+
538+> _See_ the child.
539+
540+ He is pale and thin, he wears a thin and ragged linen shirt.
541+```
542+
543+###### Produces:
544+
545+> As Gregor Samsa awoke one morning from uneasy dreams
546+ he found himself transformed in his bed into a *monstrous* vermin.
547+
548+Quote break.
549+
550+> _See_ the child.
551+
552+ He is pale and thin, he wears a thin and ragged linen shirt.
553+
554+
555+### Poem
556+
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*.
561+
562+###### Example:
563+
564+```
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.
569+```
570+###### Produces:
571+
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.
576+
577+
578+;=
579+ ;h2
580+ ;div(id "sail"): Sail Expressions
581+ ==
582+==
583+
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.
587+
588+
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
593+specifics.
594+
595+Example:
596+
597+```
598+;=
599+ ;p
600+ ;strong: Don't panic!
601+ ;br;
602+ ;small: [reactive publishing intensifies]
603+ ==
604+==
605+```
606+
607+Produces:
608+
609+
610+;=
611+ ;p
612+ ;strong: Don't panic!
613+ ;br;
614+ ;small: [reactive publishing intensifies]
615+ ==
616+==