Xetodoc

Overview

All xeto documentation uses a flavor of markdown we term xetodoc. Every library has zero or more markdown chapters which are resource files in the root directory of the lib with a ".md" extension. You can define a table of contents in "index.md" discussed below. Each markdown filename must not collide with any type or instance names to ensure consistent URIs when generated to HTML pages.

Xetodoc is formally based on Commonmark, with the following extensions:

• Shortcut Links: shortcut [link] syntax
• Section Links: every heading has a anchor id
• Tables: Github table extensions
• Videos: embedded video support for YouTube, Vimeo, and Loom
• HTML: nested HTML is explicitly disallowed

Table of Contents

A library with markdown chapters can define an order and summary of the chapters to use as table of content. The table of contents is defined in a markdown resource file named "index.md". It must be formatted using only h1 headings and lists of links as follows:

# Section Heading 1

- [Foo](Foo.md): summary of Foo
- [Bar](bar.md): summary of Bar

# Seciton Heading 2

- [Baz](Baz.md): summary of Baz
- [Qux](Qux.md): summary of Qux

Shortcut Links

Markdown links come in several flavors, but the typical format is [text](uri). Xetodoc allows this to be shortened to [uri]. Furthermore there is is built in support for linking by relative or qualified names:

--- Absolute Links ---
[ph.points::index]           Library index
[sys::Str]                   Spec type via qname
[sys::Spec.doc]              Spec slot via qname
[lib::my-instance]           Instance via qname
[doc.xeto::Xetodoc]          Markdown chapter via qname
[doc.xeto::Xetodoc#tables]   Markdown chapter via qname
[readAll()]                  Unqualified func name in namespace
[hx::readAll()]              Qualilfied func name within namespace

--- Lib Relative Links ---
[Str]                        Spec type name in lib or its depends
[Lib.version]                Spec slot dotted name in lib or its depends
[Readme]                     Markdown chapter section anchor name without .md ext
[Readme.md]                  Markdown chapter name with .md ext
[Readme#section]             Markdown chapter section anchor without .md ext
[Readme.md#section]          Markdown chapter section anchor with .md ext

--- Chapter Relative Links ---
[#section]                   Section anchor within the markdown chapter

Section Links

Every heading is mapped to a anchor id using the same rules as GitHub:

• Letters are converted to lower-case

• Spaces are replaced by hyphens (-). Any other whitespace or punctuation characters are removed

• Leading and trailing whitespace are removed

• Markup formatting is removed, leaving only the contents (for example, italics becomes italics)

• If the automatically generated anchor for a heading is identical to an earlier anchor in the same document, a unique identifier is generated by appending a hyphen and an auto-incrementing integer.

Tables

Xetodoc allows tables using the Github flavored table extension format.

Example:

| foo | bar |
| --- | --- |
| baz | qux |

Videos

Xetodoc allows embedded videos using the standard image format with special handling for the "video:" URI scheme. The following sources are supported:

1. YouTube The format for the YouTube URL is video://youtu.be/<id>?si=<si> or video://youtube/<id>?si=<si>. The id and sican be found by going to the YouTube video, clicking the 'Share' button, and inspecting the link text.

2. Loom The format for a Loom URL is video://loom/<id>?sid=<sid>. The id and sid can be found by going to the Loom video, clicking the "link" icon and inspecting the link text.

3. Vimeo: format is URL is video://vimeo/<id> or video://vimeo/<id>?h=<hash>

Complete youtube example:

![iframe title](video://youtu.be/fr-K-MVbAa8?si=dnJTcLsVdzfUfE7T)

HTML

Nested HTML is explicitly disallowed in xetodoc and will be ignored when displaying documentation.