diff --git a/content/guides/additional/udon.md b/content/guides/additional/udon.md new file mode 100644 index 0000000..bbaffed --- /dev/null +++ b/content/guides/additional/udon.md @@ -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.