@@ -0,0 +1,349 @@
1+---
2+navhome: /docs/
3+next: true
4+sort: 22
5+Title: Internals
6+---
7+_thanks to ~rovnys-ricfer for writing the original version of this_
8+
9+# Urbit-Flavored Markdown
10+
11+## overview
12+
13+Urbit-Flavored Markdown (UFM) is a minimal markup language for creating and rendering text documents,
14+with a [Markdown](https://en.wikipedia.org/wiki/Markdown)-inspired syntax. It's integrated with the Hoon programming
15+language, allowing it to be used as standalone prose in its own file or inside
16+a hoon source file, in which case it will be parsed into a tree of HTML nodes
17+using Hoon's `sail` datatype.
18+
19+UFM is stricter than Markdown and generally supports only one syntax for each
20+type of HTML node that it emits.
21+
22+### headers
23+
24+Headers in UFM begin with one or more `#` characters, followed by a space. The
25+number of leading `#`s corresponds to the resulting HTML element: `#` yields an
26+`<h1>`; `##` yields the slightly smaller `<h2>`; and so on, through `<h6>`.
27+
28+Example:
29+```
30+### Header (h3)
31+
32+##### Header (h5)
33+```
34+produces:
35+
36+> ### Header (h3)
37+
38+ ##### Header (h5)
39+
40+### lists
41+
42+A line beginning with a `-` or `+` followed by a space is interpreted as an
43+element of a list. `-` means unordered list (`<ul>`) and `+` means ordered list
44+(`<ol>`).
45+
46+Example:
47+
48+```
49+- unordered 1
50+ text on newline shows up on same line
51+- unordered 2\
52+ text on newline after `\` puts in <br> line break
53+
54+- unordered after 1 blank line
55+ - nested
56+ - double-nested
57+
58++ leading '+'
59++ leading '+'
60+- unordered '-'
61+ + nested ordered '+' item 1
62+ + nested ordered '+' item 2
63+
64++ ordered '+'
65+ + nested item 1
66+ + nested item 2
67+```
68+
69+produces:
70+
71+> - unordered 1
72+ text on newline shows up on same line
73+ - unordered 2\
74+ text on newline after `\` puts in <br> line break
75+
76+ - unordered after 1 blank line
77+ - nested
78+ - double-nested
79+
80+ + leading '+'
81+ + leading '+'
82+ - unordered '-'
83+ + nested ordered '+' item 1
84+ + nested ordered '+' item 2
85+
86+ + ordered '+'
87+ + nested item 1
88+ + nested item 2
89+
90+### blockquotes
91+
92+A section of text beginning with `> ` and indented by two spaces yields a
93+`<blockquote>` element. This blockquote can itself turn contain more UFM,
94+including more blockquotes to render nested levels of quotation.
95+
96+Example:
97+
98+```
99+> As Gregor Samsa awoke one morning from uneasy dreams
100+ he found himself _transformed_ in his bed into a *monstrous* vermin.
101+```
102+
103+produces:
104+
105+> > As Gregor Samsa awoke one morning from uneasy dreams
106+ he found himself _transformed_ in his bed into a *monstrous* vermin.
107+
108+### code blocks
109+
110+By enclosing a block of text in `\`\`\` on their own lines
111+before and after the block, the text will be treated as a code block.
112+
113+Example:
114+
115+```
116+> ```
117+ (def Y (fn [f]
118+ ((fn [x]
119+ (x x))
120+ (fn [x]
121+ (f (fn [y]
122+ ((x x) y)))))))
123+ ```
124+```
125+
126+produces:
127+
128+> ```
129+ (def Y (fn [f]
130+ ((fn [x]
131+ (x x))
132+ (fn [x]
133+ (f (fn [y]
134+ ((x x) y)))))))
135+ ```
136+
137+### poems
138+
139+A poem is a section of text with meaningful newlines. Normally in UFM,
140+newlines are treated as spaces and do not create a new line of text. If you
141+want to embed text where newlines are retained, then indent the text by
142+question with eight spaces.
143+
144+Example:
145+```
146+ A shape with lion body and the head of a man,
147+ A gaze blank and pitiless as the sun,
148+ Is moving its slow thighs, while all about it
149+ Reel shadows of the indignant desert birds.
150+```
151+produces:
152+> A shape with lion body and the head of a man,
153+ A gaze blank and pitiless as the sun,
154+ Is moving its slow thighs, while all about it
155+ Reel shadows of the indignant desert birds.
156+
157+### sail expressions
158+
159+It's possible to use Urbit-Flavored Markdown as an HTML-templating language akin to
160+PHP, ERB, JSP, or Handlebars templates. This facility derives
161+in part from the support for embedding Hoon code inside the markup.
162+There are two ways to do embed Hoon in UFM: inline expressions and `sail`.
163+[Sail](https://urbit.org/fora/posts/~2017.7.6..21.27.00..bebb~/)
164+is a DSL within Hoon for creating XML nodes, including HTML. It can
165+be used directly within UFM to provide scripting capability and also to
166+provide more fine-grained control over the resulting HTML.
167+
168+Example:
169+```
170+;=
171+ ;p
172+ ;strong: Don't panic!
173+ ;br;
174+ ;small: [reactive publishing intensifies]
175+ ==
176+==
177+```
178+
179+produces:
180+> ;=
181+ ;p
182+ ;strong: Don't panic!
183+ ;br;
184+ ;small: [reactive publishing intensifies]
185+ ==
186+ ==
187+
188+_Note:
189+[Urbit's web-publishing system](https://urbit.org/docs/arvo/web-apps/)
190+currently does not apply `<style>` elements or element attributes,
191+which are supported in `sail` syntax. Future versions of the publishing
192+system will rectify this._
193+
194+### horizontal rules
195+
196+`---` on its own line produces an `<hr>` element, the 'horizontal rule'.
197+This is rendered as a horizontal line the width of its containing paragraph.
198+
199+Example:
200+```
201+Above the line
202+---
203+Below the line
204+```
205+> :: produces:\
206+ Above the line
207+ ---
208+ Below the line
209+
210+### inline markup
211+
212+In addition to the above, UFM includes several options for marking up
213+inline text.
214+
215+##### bold
216+
217+Enclose some text in asterisks to boldly render it inside a `<b>` element.
218+
219+Example:
220+```
221+The first rule of tautology club is
222+*the first rule of tautology club*.
223+```
224+produces:\
225+
226+> The first rule of tautology club is
227+ *the first rule of tautology club*.
228+
229+##### italics
230+
231+Surrounding text with `_` on each side will cause it to appear
232+in italics, using an <i> element.
233+
234+Example:
235+```
236+Bueller? _Bueller?_
237+```
238+
239+produces:
240+
241+Bueller? _Bueller?_
242+
243+##### double quote
244+
245+Text enclosed in double quotes (`"`) will be rendered with
246+opening and closing quotes.
247+
248+Example:
249+```
250+"Yes," he said. "That is the way with him."
251+```
252+produces:\
253+
254+"Yes," he said. "That is the way with him."
255+
256+##### backslash escape
257+
258+A backslash directly before a word (with no spaces) will be interpreted
259+as an escape character, causing it to be rendered raw.
260+
261+Example:
262+```
263+Here is some *bold* text.
264+Here is some \*not bold\* text.
265+```
266+produces:
267+
268+Here is some *bold* text.
269+Here is some \*not bold\* text.
270+
271+##### trailing backslash
272+
273+A backslash at the end of a line inserts a line break (`<br>`)
274+after that line. This contrasts with the normal UFM behavior of
275+converting newlines to spaces.
276+
277+Example:
278+```
279+I wonder how long each line
280+will be if I put backslashes\
281+at the ends of the lines.
282+```
283+produces:
284+
285+I wonder how long each line
286+will be if I put backslashes\
287+at the ends of the lines.
288+
289+##### inline code literal
290+
291+Enclosing some text in ``` characters will cause it to be displayed as code,
292+inside a <code> element with monospace font and a different background color.
293+
294+Example:
295+```
296+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
297+```
298+produces:\
299+
300+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
301+
302+Also, using the `++` prefix before a word will cause the word
303+to be rendered as code, since that's the standard notation
304+for an `arm` in Hoon.
305+
306+Example:
307+```
308+The UFM parser is part of ++vast.
309+```
310+produces:\
311+
312+The UFM parser is part of ++vast.
313+
314+##### Hoon constants
315+
316+Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)
317+that can be used in UFM as well. They will appear inside a <code> element like
318+inline code.
319+
320+Example:
321+
322+```
323+~2017.8.29 \
324+0xdead.beef \
325+%term
326+```
327+
328+produces:\
329+
330+~2017.8.29 \
331+0xdead.beef \
332+%term
333+
334+##### url
335+
336+To insert a hyperlink, put the text content of the link in `[]` brackets
337+followed by the destination URL in `()` parentheses. Note that the text
338+of the displayed link can contain Markdown styling.
339+
340+Example:
341+
342+```
343+A [Hoon `core`](https://urbit.org/docs/hoon/concepts/#-core-object)
344+is similar to an object in a traditional programming langauge.
345+```
346+produces:\
347+
348+A [Hoon `core`](https://urbit.org/docs/hoon/concepts/#-core-object)
349+is similar to an object in a traditional programming langauge.