shrub/web/unmark/doc.umd

::   :-  :*  title+"urbit-flavored markdown docs"
::           author+"ted blackman"
::           date+~2017.8.25
::       ==
::  
;>

# udon: urbit-flavored markdown

## overview

Udon is a minimal markup language for creating and rendering text documents,
with a markdown-inspired syntax. It's integrated with the hoon programming
language, allowing it to be used as standalone prose in its own file or inside
a hoon source file, in which case it will be parsed into a tree of HTML nodes
using hoon's `sail` datatype.

Udon is stricter than markdown and generally supports only one syntax for each
type of HTML node it emits.

### headers

Headers in udon begin with one or more `#` characters, followed by a space. The
number of leading `#`s corresponds to the resulting HTML element: `#` yields an
`<h1>`, `##` yields an `<h2>`, and so on through `<h6>`.

Example:
```
### Header (h3)

##### Header (h5)
```
produces:

> ### Header (h3)

  ##### Header (h5)

### lists

A line beginning with a `-` or `+` followed by a space is interpreted as an
element of a list. `-` means unordered list (`<ul>`) and `+` means ordered list
(`<ol>`).

Example:

```
- unordered 1
  text on newline shows up on same line
- unordered 2\
  text on newline after `\` puts in <br> line break

- unordered after 1 blank line
  - nested
    - double-nested

+ leading '+'
+ leading '+'
- unordered '-'
  + nested ordered '+' item 1
  + nested ordered '+' item 2

+ ordered '+'
  + nested item 1
  + nested item 2
```

produces:

> - unordered 1
    text on newline shows up on same line
  - unordered 2\
    text on newline after `\` puts in <br> line break

  - unordered after 1 blank line
    - nested
      - double-nested

  + leading '+'
  + leading '+'
  - unordered '-'
    + nested ordered '+' item 1
    + nested ordered '+' item 2

  + ordered '+'
    + nested item 1
    + nested item 2

### blockquotes

A section of text beginning with `> ` and indented by two spaces yields a
`<blockquote>` element. This blockquote can itself turn contain more udon,
including more blockquotes to render nested levels of quotation.

Example:

```
> As Gregor Samsa awoke one morning from uneasy dreams 
  he found himself _transformed_ in his bed into a *monstrous* vermin.
```

produces:

> > As Gregor Samsa awoke one morning from uneasy dreams 
    he found himself _transformed_ in his bed into a *monstrous* vermin.

### code blocks

By enclosing a block of text in `\`\`\` on their own lines
before and after the block, the text will be treated as a code block.

Example:

```
> ```
  (def Y (fn [f]
         ((fn [x]
            (x x))
          (fn [x]
            (f (fn [y]
                 ((x x) y)))))))
  ```
```

produces:

> ```
  (def Y (fn [f]
         ((fn [x]
            (x x))
          (fn [x]
            (f (fn [y]
                 ((x x) y)))))))
  ```

### poems

A poem is a section of text with meaningful newlines.  Normally in udon,
newlines are treated as spaces and do not create a new line of text. If you
want to embed text where newlines are retained, then indent the text by
question with eight spaces.

Example:
```
        A shape with lion body and the head of a man,
        A gaze blank and pitiless as the sun,
        Is moving its slow thighs, while all about it
        Reel shadows of the indignant desert birds.
```
produces:
>         A shape with lion body and the head of a man,
          A gaze blank and pitiless as the sun,
          Is moving its slow thighs, while all about it
          Reel shadows of the indignant desert birds.

### sail expressions

It's possible to use udon as an HTML templating language akin to
PHP, ERB, JSP, or Handlebars templates. This facility derives
in part from the support for embedding hoon code inside the markup.
There are two ways to do embed hoon in udon: inline expressions and sail.
[Sail](https://urbit.org/fora/posts/~2017.7.6..21.27.00..bebb~/)
is a DSL within hoon for creating XML nodes, including HTML. It can
be used directly within udon to provide scripting capability and also to
provide more fine-grained control over the resulting HTML. 

Example:
```
;=
  ;p
    ;strong: Don't panic!
    ;br;
    ;small: [reactive publishing intensifies]
  ==
==
```

produces:
> ;=
    ;p
      ;strong: Don't panic!
      ;br;
      ;small: [reactive publishing intensifies]
    ==
  ==

_Note:
[urbit's web publishing system](https://urbit.org/docs/arvo/web-apps/)
currently does not apply `<style>` elements or element attributes,
which are supported in sail syntax. Future versions of the publishing
system will rectify this._

### horizontal rules

`---` on its own line produces an `<hr>` element, the 'horizontal rule'.
This is rendered as a horizontal line the width of its containing paragraph.

Example:
```
Above the line
---
Below the line
```
> ::  produces:\
  Above the line
  ---
  Below the line

### inline markup

In addition to the above, udon includes several options for marking up
inline text.

##### bold

Enclose some text in asterisks to boldly render it inside a `<b>` element.

Example:
```
The first rule of tautology club is
*the first rule of tautology club*.
```
produces:\

> The first rule of tautology club is
  *the first rule of tautology club*.

##### italics

Surrounding text with `_` on each side will cause it to appear
in italics, using an <i> element.

Example:
```
Bueller? _Bueller?_
```

produces:

Bueller? _Bueller?_

##### double quote

Text enclosed in double quotes (`"`) will be rendered with
opening and closing quotes.

Example:
```
"Yes," he said. "That is the way with him."
```
produces:\

"Yes," he said. "That is the way with him."

##### backslash escape

A backslash directly before a word (with no spaces) will be interpreted
as an escape character, causing it to be rendered raw.

Example:
```
Here is some *bold* text.
Here is some \*not bold\* text.
```
produces:

Here is some *bold* text.
Here is some \*not bold\* text.

##### trailing backslash

A backslash at the end of a line inserts a line break (`<br>`)
after that line. This contrasts with the normal udon behavior of
converting newlines to spaces.

Example:
```
I wonder how long each line
will be if I put backslashes\
at the ends of the lines.
```
produces:

I wonder how long each line
will be if I put backslashes\
at the ends of the lines.

##### inline code literal

Enclosing some text in ``` characters will cause it to be displayed as code,
inside a <code> element with monospace font and a different background color.

Example:
```
`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.
```
produces:\

`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.

Also, using the `++` prefix before a word will cause the word
to be rendered as code, since that's the standard notation
for an arm in hoon.

Example:
```
The udon parser is part of ++vast.
```
produces:\

The udon parser is part of ++vast.

##### hoon constants

Hoon has several syntactic forms for literals (numbers, strings, dates, etc.)
that can be used in udon as well. They will appear inside a <code> element like
inline code.

Example:

```
~2017.8.29 \
0xdead.beef \
%term
```

produces:\

~2017.8.29 \
0xdead.beef \
%term

##### url

To insert a hyperlink, put the text content of the link in `[]` brackets
followed by the destination URL in `()` parentheses. Note that the text
of the displayed link can contain markdown styling.

Example:

```
A [hoon `core`](https://urbit.org/docs/hoon/concepts/#-core-object)
is similar to an object in a traditional programming langauge.
```
produces:\

A [hoon `core`](https://urbit.org/docs/hoon/concepts/#-core-object)
is similar to an object in a traditional programming langauge.