Note: this section is mostly useful if you're writing a mark conversion method. For marks that are already supported and you can use directly, see further down this page.
%docs app supports any mark, as long as it has a conversion method to its
%docu mark. The
%docu mark is not expected to be used directly to write documentation, its purpose is to be a mark conversion target.
%docu mark expects a
$manx is how an XML node structure is represented in hoon. See Section 5e of the standard library reference for details. A
$manx is what
++en-xml:html decode/encode raw XML strings from/to.
%docu mark will technically accept any
$manx, but the
%docs agent itself makes some changes and imposes some additional rules:
- The root element must be a
<h3>elements that are direct children of the root
<div>will be used to make the table of contents. Other header levels will not be included in the table of contents, but they can still be used.
<h3>can also be used at deeper levels, but they also won't be included in the table of contents.
- Only these tags are allowed:
- Inside the
<h3>headers that are direct children of the root
<div>(and will therefore be used in the table of contents), only a subset of the tags listed above are allowed:
- All attributes will be stripped from all elements (you can still include them but they'll be removed), with the following exceptions:
altattributes in an
hrefattribute in an
classattribute in a
<pre>tag beginning with
class="language-hoon"). This is not currently used for anything but will be used for syntax highlighting in the future.
Note: table elements are not currently supported but will likely be added in a future release.
The following marks are supported by the %docs app and you can use them to write docs right away.
Udon is a markdown-like language native to hoon, with a parser built into the hoon compiler. Here is its syntax in brief:
- The first line of the
.udondocument 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
_foo_) will be made italic.
- Bold: content wrapped in single
*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 constants: Udon will automatically render any values with atom aura syntax as inline code. It'll also render arms like
+*foo:bar:baz, as inline code.
- Sail: this is hoon's native XML syntax. Udon will parse it, execute it, and include the
+$manxes produced in the resulting document. This means you can embed arbitrary hoon in the document. There is little formal sail documentation, but you can refer to the
;(mic) rune reference for most of its runes and some rudimentary examples.
Note: Udon is quite strict on its syntax, and may fail to parse if it's incorrect.
%docs app supports plain
.txt files. The file will be rendered as a preformatted codeblock with wrapping.
Ordinary HTML files may be used, but note the tag and structural restrictions described in the
%docu mark description above.
Gemtext is an ultra-minimal markup format developed for the Gemini project, an internet protocol for serving light-weight hypertext, inspired by Gopher. Its file extension is
Gemtext interprets things on a line-by-line basis, and does not support different types on a single line. Every line is a separate element, with the exception of fenced codeblocks which may span multiple lines. In brief, here is the syntax:
- Paragraphs: Plain text on a single line constitutes a paragraph. Note hard-wrapping is not supported.
- Links: lines beginning with
=>followed by a space create a link. After the space, the target URL is given. After the URL, there may optionally be a space and then some display text for the link. If no displace text is given, the URL itself will be displayed.
- Codeblocks: triple-backticks at the beginning of a line begin and end a codeblock. All text in between will be rendered verbatim in a monospace font. The opening backticks may optionally be followed by some text, which will be used as the language tag.
- Headings: 1-3
#s followed by text create a heading. The number of
#s determine the heading level.
- Lists: lines beginning with
*followed by a space and then text will create a list item.
- Quotes: lines beginning with
>followed by a space creates a blockquote.