@@ -0,0 +1,349 @@
7+_thanks to ~rovnys-ricfer for writing the original version of this_
9+# Urbit-Flavored Markdown
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.
19+UFM is stricter than Markdown and generally supports only one syntax for each
20+type of HTML node that it emits.
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>`.
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
50+ text on newline shows up on same line
52+ text on newline after `\` puts in <br> line break
54+- unordered after 1 blank line
61+ + nested ordered '+' item 1
62+ + nested ordered '+' item 2
72+ text on newline shows up on same line
74+ text on newline after `\` puts in <br> line break
76+ - unordered after 1 blank line
83+ + nested ordered '+' item 1
84+ + nested ordered '+' item 2
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.
99+> As Gregor Samsa awoke one morning from uneasy dreams
100+ he found himself _transformed_ in his bed into a *monstrous* vermin.
105+> > As Gregor Samsa awoke one morning from uneasy dreams
106+ he found himself _transformed_ in his bed into a *monstrous* vermin.
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.
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.
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.
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.
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.
172+ ;strong: Don't panic!
174+ ;small: [reactive publishing intensifies]
182+ ;strong: Don't panic!
184+ ;small: [reactive publishing intensifies]
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._
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.
212+In addition to the above, UFM includes several options for marking up
217+Enclose some text in asterisks to boldly render it inside a `<b>` element.
221+The first rule of tautology club is
222+*the first rule of tautology club*.
226+> The first rule of tautology club is
227+ *the first rule of tautology club*.
231+Surrounding text with `_` on each side will cause it to appear
232+in italics, using an <i> element.
245+Text enclosed in double quotes (`"`) will be rendered with
246+opening and closing quotes.
250+"Yes," he said. "That is the way with him."
254+"Yes," he said. "That is the way with him."
256+##### backslash escape
258+A backslash directly before a word (with no spaces) will be interpreted
259+as an escape character, causing it to be rendered raw.
263+Here is some *bold* text.
264+Here is some \*not bold\* text.
268+Here is some *bold* text.
269+Here is some \*not bold\* text.
271+##### trailing backslash
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.
279+I wonder how long each line
280+will be if I put backslashes\
281+at the ends of the lines.
285+I wonder how long each line
286+will be if I put backslashes\
287+at the ends of the lines.
289+##### inline code literal
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.
296+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
300+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
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.
308+The UFM parser is part of ++vast.
312+The UFM parser is part of ++vast.
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
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.
343+A [Hoon `core`](https://urbit.org/docs/hoon/concepts/#-core-object)
344+is similar to an object in a traditional programming langauge.
348+A [Hoon `core`](https://urbit.org/docs/hoon/concepts/#-core-object)
349+is similar to an object in a traditional programming langauge.