# File Format ## `%docu` mark {% hint style="info" %} **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. {% endhint %} The `%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. The `%docu` mark expects a `$manx`. A `$manx` is how an XML node structure is represented in hoon. See [Section 5e](/hoon/stdlib/5e.md#manx) of the standard library reference for details. A `$manx` is what `+de-xml:html` and `+en-xml:html` decode/encode raw XML strings from/to. The `%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 `
`. * `

`, `

`, and `

` elements that are direct children of the root `
` 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. `

`, through `

` 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 `
        `, `
        `, and `
        ` headers that are direct children of the root `
        ` (and will therefore be used in the table of contents), only a subset of the tags listed above are allowed: ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, `
        ` tag beginning with `language-` (e.g. `class="language-hoon"`). This is not currently used for anything but will be used for syntax highlighting in the future.

{% hint style="info" %}
**Note**: table elements are not currently supported but will likely be added in a future release.
{% endhint %}

***

## Included marks 

The following marks are supported by the %docs app and you can use them to write docs right away.

### `%udon` 

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 `.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 constants**: 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. There is little formal sail documentation, but you can refer to the [`;` (mic) rune reference](/hoon/rune/mic.md) for most of its runes and some rudimentary examples.

{% hint style="info" %}
**Note**: Udon is quite strict on its syntax, and may fail to parse if it's incorrect.
{% endhint %}

### `%txt` 

The `%docs` app supports plain `.txt` files. The file will be rendered as a preformatted codeblock with wrapping.

### `%html` 

Ordinary HTML files may be used, but note the tag and structural restrictions described in the `%docu` mark description above.

### `%gmi` 

Gemtext is an ultra-minimal markup format developed for the [Gemini project](https://en.wikipedia.org/wiki/Gemini_\(protocol\)), an internet protocol for servinglight-weight hypertext, inspired by Gopher. Its file extension is `.gmi`.

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.urbit.org/build-on-urbit/tools/docs-app/file-format.md?ask=
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.