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