mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-16 17:20:35 +03:00
commit
dc48c16690
179
content/guides/additional/udon.md
Normal file
179
content/guides/additional/udon.md
Normal file
@ -0,0 +1,179 @@
|
||||
+++
|
||||
title = "Udon (Markdown-esque)"
|
||||
description = "Learn the basics of Udon"
|
||||
weight = 97
|
||||
+++
|
||||
|
||||
Udon is a domain-specific language for composing documents. Udon is very similar
|
||||
to Markdown, but with some minor variation in syntax and some additional
|
||||
Urbit-related affordances.
|
||||
|
||||
Udon files are compiled to `manx`es (Urbit's XHTML/XML representation), so can
|
||||
easily be used to publish documents to the browser. Udon also allows you to
|
||||
embed arbitrary [Sail](/guides/additional/sail) syntax, which itself allows
|
||||
embedding arbitrary Hoon, so it can be quite powerful for dynamic content when
|
||||
compiled against an appropriate subject.
|
||||
|
||||
This document will walk through the basics of Udon and its syntax.
|
||||
|
||||
## Basic example
|
||||
|
||||
Here's an example of an Udon file and its various allowed syntax.
|
||||
|
||||
````
|
||||
;>
|
||||
|
||||
# H1
|
||||
|
||||
## H2
|
||||
|
||||
### H3
|
||||
|
||||
#### H4
|
||||
|
||||
##### H5
|
||||
|
||||
###### H6
|
||||
|
||||
This is a paragraph with _italics_, *bold* and
|
||||
`inline code`. Sentences can be hard wrapped.
|
||||
|
||||
|
||||
- unordered
|
||||
- list
|
||||
|
||||
+ ordered
|
||||
+ list
|
||||
|
||||
[link](https://urbit.org)
|
||||
|
||||
![image](https://media.urbit.org/guides/additional/dist/wut.svg)
|
||||
|
||||
```
|
||||
fenced codeblock
|
||||
(note language spec not supported)
|
||||
```
|
||||
|
||||
horizontal rule:
|
||||
---
|
||||
|
||||
> block quotes
|
||||
may be hard-wrapped if indented
|
||||
|
||||
Backslash at end\
|
||||
of line adds linebreak
|
||||
|
||||
Udon syntax may be prefixed with \*backslashes\* to escape.
|
||||
|
||||
Hoon atom literals like ~sampel-palnet and ~.foo will
|
||||
be rendered as inline code.
|
||||
|
||||
;table
|
||||
;tr
|
||||
;td: Arbitrary
|
||||
;td: Sail
|
||||
==
|
||||
;tr
|
||||
;td: is
|
||||
;td: allowed
|
||||
==
|
||||
==
|
||||
````
|
||||
|
||||
## Syntax summary
|
||||
|
||||
- The first line of a `.udon` document *must* be a single rune: `;>`. This tells
|
||||
the compiler to interpret everything following as udon.
|
||||
- **Paragraphs**: Content on a single line will be made into a paragraph.
|
||||
Paragraphs may be hard-wrapped, so consecutive lines of text will become a
|
||||
single paragraph. The paragraph will be ended by an empty line or other block
|
||||
element.
|
||||
- **Headers**: lines beginning with 1-6 `#`s followed by a single space and then
|
||||
some content (e.g. `## foo`) will be made into headers. The number of `#`s
|
||||
dictates the header level.
|
||||
- **Italics**: content wrapped in single `_`s (e.g. `_foo_`) will be made italic.
|
||||
- **Bold**: content wrapped in single `*`s (e.g. `*foo*`) will be made bold.
|
||||
- **Unordered lists**: lines beginning with `-` followed by a space will be made
|
||||
into items in a list. List lines can be hard-wrapped, with two spaces
|
||||
beginning each subsequent line to be included in the list. Lists can be nested
|
||||
by indenting the `-`s a further two spaces for each level of nesting.
|
||||
- **Ordered lists**: lines beginning with `+` followed by a space will be made into
|
||||
ordered lists, and numbered in the order they appear. These have the same
|
||||
wrapping and nesting logic as unordered lists.
|
||||
- **Links**: this is standard markdown syntax: square bracks containing the display
|
||||
content and then parentheses containing the URL, e.g.
|
||||
`[foo](http://example.com)`. The URL may also be a relative link or an anchor
|
||||
link.
|
||||
- **Images**: this is also standard markdown; a link with an exclamation mark at the
|
||||
beginning, e.g. `![foo](http://example.com/image.png)`. The square brackets
|
||||
contain the alt-text and the the parentheses contain the image URL.
|
||||
- **Inline code**: text wrapped in single backticks will be rendered verbatim in a
|
||||
monospace font.
|
||||
- **Fenced codeblocks**: Triple-backticks on their own line begin and end a
|
||||
codeblock. All lines in between will be rendered verbatim in a monospace font.
|
||||
Note that udon does not support a language specification after the opening
|
||||
backticks like markdown does.
|
||||
- **Horizontal rules**: Three or more hyphens (`---`) will create a horizontal rule.
|
||||
- **Block quotes**: a line beginning with `>` creates a block quote. This may be
|
||||
hard-wrapped, as long as the next line is indented two spaces. Block quotes
|
||||
may contain anything, including other blockquotes.
|
||||
- **Line breaks**: A line ending in a single backslash will have a line break
|
||||
inserted at the end, so it will not flow together with the subsequent line as
|
||||
is usually the case.
|
||||
- **Escape characters**: You may prefix Udon syntax with a backslash to have it
|
||||
treated as the literal text.
|
||||
- **Hoon literals and wings**: Udon will automatically render any values with
|
||||
atom aura syntax as inline code. It'll also render arms like `++foo:bar`,
|
||||
`+$baz`, and `+*foo:bar:baz, as inline code.`
|
||||
- **Sail**: this is hoon's native XML syntax. Udon will parse it, execute it, and
|
||||
include the `+$manx`es produced in the resulting document. This means you can
|
||||
embed arbitrary hoon in the document.
|
||||
|
||||
{% callout %}
|
||||
|
||||
Note that Udon is quite strict on its syntax, and may fail to parse if it's
|
||||
incorrect.
|
||||
|
||||
{% /callout %}
|
||||
|
||||
## Udon Mode
|
||||
|
||||
An Udon file has a `.udon` extension (an `%udon` mark).
|
||||
|
||||
The first thing in an Udon file must be the `micgar` rune: `;>`
|
||||
|
||||
Micgar tells the Hoon compiler to interpret everything afterwards as Udon.
|
||||
Udon-mode ends at the end of the file; there's no way to terminate micgar before
|
||||
that. Udon is therefore useful for whole documents rather than embedding
|
||||
snippets in other Hoon files.
|
||||
|
||||
The Hoon compiler will produce a `manx` as a result.
|
||||
|
||||
To scry out a file, compile it against the standard library, and stringify the
|
||||
resulting XHTML, you can do:
|
||||
|
||||
```
|
||||
%- crip
|
||||
%- en-xml:html
|
||||
!< manx
|
||||
%+ slap !>(..zuse)
|
||||
%- ream
|
||||
.^(@t %cx /=the-desk=/the-file/udon)
|
||||
```
|
||||
|
||||
Note you may want to provide more than just `..zuse` in the subject (like a
|
||||
`bowl`), or if you're automatically building untrusted code, you may want to
|
||||
provide less. It depends on your use case.
|
||||
|
||||
You can alternatively import and build udon files at compile time with a [`/*`
|
||||
(fastar) Ford rune](/reference/hoon/rune/fas#-fastar) specifying an `%elem` mark
|
||||
(which produces a `manx`), although note it compiles the Udon against an empty
|
||||
subject, so Hoon in embedded Sail won't have access to standard library
|
||||
functions. A mark conversion gate from `%udon` to `%elem` is another option.
|
||||
|
||||
## Examples
|
||||
|
||||
The [Docs App](https://urbit.org/applications/~pocwet/docs) includes a [a few
|
||||
files written in
|
||||
Udon](https://github.com/tinnus-napbus/docs-app/tree/main/bare-desk/doc) which
|
||||
are useful as a reference.
|
Loading…
Reference in New Issue
Block a user