` tag.
+ - A `class` attribute in a `` 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.
+
+{% callout %}
+**Note**: table elements are not currently supported but will likely be added
+in a future release.
+{% /callout %}
+
+---
+
+## 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](/reference/hoon/rune/mic) for most of its runes and some
+ rudimentary examples.
+
+{% callout %}
+**Note**: Udon is quite strict on its syntax, and may fail to parse if it's
+incorrect.
+{% /callout %}
+
+### `%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://gemini.circumlunar.space/), an internet protocol for serving
+light-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.
diff --git a/content/reference/additional/docs-app/index-file.md b/content/reference/additional/docs-app/index-file.md
new file mode 100644
index 0000000..04f6f74
--- /dev/null
+++ b/content/reference/additional/docs-app/index-file.md
@@ -0,0 +1,45 @@
++++
+title = "Index File"
+weight = 10
+template = "doc.html"
++++
+
+Each desk with docs may include a `doc.toc` file in its root. A `doc.toc` file
+looks something like this:
+
+```
+/dev Developer
+ /hark-store Hark-store
+ /overview/udon Overview
+ /types/udon Data Types
+ /pokes/udon Pokes
+ /paths/udon Subscription Paths
+ /scry/udon Scry Endpoints
+ /settings-store Settings-store
+ /overview/udon Overview
+ /types/udon Data Types
+ /pokes/udon Pokes
+ /paths/udon Subscription Paths
+ /scry/udon Scry Endpoints
+```
+
+Each line contains a pair of path and title with at least one space in between.
+A path with a single element (such as `/dev` and `/hark-store`) denotes a
+directory. A path with two elements (such as `/overview/udon`) denotes a file,
+where the first element is the name and the second is the mark.
+
+Any directory structure and depth is allowed. The hierarchy is determined by
+indentation. Each double-space indent denotes a nesting level. Two spaces is one
+level, four spaces is two levels, etc.
+
+The root is the `/doc` directory of your desk, it should not be explicitly
+listed.
+
+The title specified will be displayed at the top of the document and in the
+table of contents for the desk.
+
+If no `doc.toc` file is included, but a desk does have other files under
+`/doc`, the Docs app will infer a table of contents from the directory
+structure, and _all_ files will be included. Files are ordered alphabetically,
+except that 'overview' always come first. For titles, hyphens in the filename
+are replaced with spaces and the whole is converted to Title Case.
diff --git a/content/reference/additional/docs-app/overview.md b/content/reference/additional/docs-app/overview.md
new file mode 100644
index 0000000..f2a9e79
--- /dev/null
+++ b/content/reference/additional/docs-app/overview.md
@@ -0,0 +1,47 @@
++++
+title = "Overview"
+weight = 1
+template = "doc.html"
++++
+
+The `%docs` app allows you to include documentation with the desks you
+distribute, making them available for easy browsing by users and developers.
+
+The `%docs` app will automatically detect and publish any docs included with
+any installed desks. As long as they're in the correct place and of a filetype
+with appropriate `mark` conversion methods, they'll be picked up.
+
+A `doc.toc` file may be included in the root of the desk, specifying the files
+to be included, their `mark`s, and their titles. See the [Index
+File](/reference/additional/docs-app/index-file) section for details.
+
+The files will be in a `/doc` directory in the root of the desk. They may be of
+any filetype, as long as it has conversion methods to the `%docu` mark used by
+the `%docs` app. The `%docs` app includes parsers and conversion methods for
+the following marks by default:
+
+- `%txt` - Ordinary `.txt` text files.
+- `%udon` - A markdown-like format that supports embedded hoon.
+- `%gmi` - An ultra-minimalist markup format called "gemtext".
+- `%html` - An ordinary `.html` file.
+
+For more details of these file formats, as well as details of the `%docu` mark
+and other format requirements of the `%docs` app, see the [File
+Format](/reference/additional/docs-app/file-format) section.
+
+Apart from the `mark` and location requirements described above, there are no
+particular restrictions on how you organise your docs, or what docs you
+include. There are, however, some general recommendations detailed in the
+[Suggested Structure](/reference/additional/docs-app/structure) section.
+
+## Dev desk
+
+To include docs in your own desk, there are a few files you'll need (mark
+files, etc). These are included in the `docs-dev` dev desk in the [github
+repo](https://github.com/tinnus-napbus/docs-app). These files are all
+symlinked, so you'll need to clone the whole repo, then copy them across with
+something like:
+
+```
+cp -rL git/docs-app/docs-dev/* /path/to/your/development/desk
+```
diff --git a/content/reference/additional/docs-app/structure.md b/content/reference/additional/docs-app/structure.md
new file mode 100644
index 0000000..b8ad8a4
--- /dev/null
+++ b/content/reference/additional/docs-app/structure.md
@@ -0,0 +1,91 @@
++++
+title = "Suggested Structure"
+weight = 15
+template = "doc.html"
++++
+
+Here we'll discuss recommendations and best practices for your docs. The
+%docs app doesn't impose any restrictions on the structure of your docs, so
+you're free to do things differently if you feel it's appropriate.
+
+## User docs
+
+For the most part, user documentation depends on the nature of your app, so it's
+up to you how you document it. There are, however, a couple of things that are
+advisable to include:
+
+### General info
+
+You should include some of the following information (as appropriate) in either
+a distinct informational document or at the top of the first document:
+
+- **Publisher/developer/contributors**: Your `@p`, the `@p` you distribute the app
+ from, people who have helped build the app, etc.
+- **License**: MIT, GPL, etc.
+- **Source**: Github link (or similar) for the repo containing the source code.
+- **Issues**: Where to file issues (typically also the Github repo).
+- **Group**: If you have a group associated with your app (for support, discussion,
+ or what have you), you can include the `~host/group-name`.
+- Any other metadata, links, info, etc, you feel are appropriate to include.
+
+### Changelog
+
+Another useful document is a changelog. For each version you release, you can
+add a new section at the top with the version number, release date, and a brief
+summary of the changes.
+
+---
+
+## Developer docs
+
+Like user docs, you're free to document things as you see fit, but it's helpful
+to include particular things with a standard format. These are documented
+below.
+
+{% callout %}
+**Note**: If your desk has a dev version, it's advisable to link to it
+somewhere sensible in the developer documentation.
+{% /callout %}
+
+### API Reference
+
+If there's any chance other developers will want to interface with agents on
+your desk, you should include reference information about the scry endpoints,
+pokes, subscription paths, and (if appropriate) data types of each agent.
+
+These things can either be on a single page, or each have their own separate
+page, depending on their complexity.
+
+#### Scry endpoints
+
+Scry endpoints may either be organised by their paths or by short summaries of
+each endpoint's purpose. Scry paths should be in the format
+`/[care]/rest/of/path`, like `/x/foo/bar`. Any variable parts of the scry path
+should have square brackets like `/x/foo/[ship]`. The data type of the response
+should be specified, and it's helpful to include an example of a scry and the
+pretty-printed response in a codeblock.
+
+#### Pokes
+
+Any poke actions an agent will accept should be documented. It's helpful to
+include an example poke. You may also wish to provide a JSON example if people
+can interact with your agent through Eyre's channel system or similar.
+
+If your agent's pokes are organised around something like an "action" tagged
+union structure, the poke reference might work better as a kind of data type
+reference for that action structure rather than specifically pokes.
+
+#### Subscriptions
+
+Subscription paths should be documented in a similar manner to the scry
+reference. If the updates your agent can send out to subscribers are organised
+around something like an "update" tagged union structure, the subscription
+reference might work better as just a brief path reference, and documentation of
+the updates can be done separately.
+
+#### Data types
+
+The inclusion of a data types section depends on the complexity of an agent's
+data types. If such a reference is appropriate, it's best to structure it with a
+separate section for each type. The type definition should be included in a
+codeblock, as well as a brief description of its purpose.