mirror of
https://github.com/urbit/shrub.git
synced 2025-01-05 19:46:50 +03:00
Finished first draft of docs. Left in TODO for fixing code blocks in blockquotes
This commit is contained in:
Ted Blackman
parent
a9aaa08c10
commit
bba0b68585
@ -12,10 +12,8 @@
|
||||
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 XML nodes
|
||||
(hoon's `sail` datatype).
|
||||
|
||||
## syntax
|
||||
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.
|
||||
@ -32,9 +30,9 @@ Example:
|
||||
|
||||
##### Header (h5)
|
||||
```
|
||||
> produces:
|
||||
produces:
|
||||
|
||||
### Header (h3)
|
||||
> ### Header (h3)
|
||||
|
||||
##### Header (h5)
|
||||
|
||||
@ -67,9 +65,9 @@ Example:
|
||||
+ nested item 2
|
||||
```
|
||||
|
||||
> produces:
|
||||
produces:
|
||||
|
||||
- unordered 1
|
||||
> - unordered 1
|
||||
text on newline shows up on same line
|
||||
- unordered 2\
|
||||
text on newline after `\` puts in <br> line break
|
||||
@ -101,9 +99,9 @@ Example:
|
||||
he found himself _transformed_ in his bed into a *monstrous* vermin.
|
||||
```
|
||||
|
||||
> produces:
|
||||
produces:
|
||||
|
||||
> As Gregor Samsa awoke one morning from uneasy dreams
|
||||
> > As Gregor Samsa awoke one morning from uneasy dreams
|
||||
he found himself _transformed_ in his bed into a *monstrous* vermin.
|
||||
|
||||
### code blocks
|
||||
@ -124,7 +122,9 @@ Example:
|
||||
```
|
||||
```
|
||||
|
||||
> produces:
|
||||
produces:
|
||||
|
||||
> TODO: fix code block on first line of blockquote
|
||||
```
|
||||
(def Y (fn [f]
|
||||
((fn [x]
|
||||
@ -148,8 +148,8 @@ Example:
|
||||
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,
|
||||
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.
|
||||
@ -160,6 +160,190 @@ 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 is a DSL within hoon for creating XML nodes, including HTML. It can
|
||||
[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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user