Skip to content

Textile Formatting Guide

The supported Textile surface for Rotkeeper sources: what Oliver renders, what falls back to literal text, and the dialects that must stay literal.

Browse Docs pages

✒️ Textile Formatting Guide

Textile is the older, terser cousin of Markdown: same frontmatter, same .soul.md sidecars, same page.md → page.html fate — but the body syntax is Textile, and Oliver’s Textile tastes are narrower than its CommonMark ones. This page is itself a .textile source; what you see rendered is what the dialect produces.

A source file carries its fate in its extension. A .textile file always renders as Textile, whatever “input_format” says in rotkeeper.yaml. A .md file renders as Textile only when that config toggle is set. The full invocation contract lives in the Oliver Renderer Contract.

Headings

A heading is a “h” plus a level and a period: “h1.” down to “h6.”. This page’s title above is “h1.”; the sections below are “h2.”.

Emphasis

Wrap text in a single asterisk pair for bold, a single underscore pair for italic. Nest freely; combine.

This whole line is bold. Inline bold and italic mix well, and nested emphasis works.

Strikethrough uses a single hyphen pair: like this. Underline uses a plus pair: like this.

Links

A link is "label":target. A title in parentheses after the label becomes the hover title. Parentheses in the URL itself clash with the title syntax and get eaten — keep link URLs parenthetical-free.

Textile on Wikipedia is external. Bare URLs are links without ceremony: https://opencode.ai

Internal links point at .md or .textile sources and the renderer rewrites them to .html, exactly like Markdown links. This sentence links the Textile Showcase — the rewrite is why the target is .html in the rendered page.

Images

A bare image is a URL in exclamation marks:

The alt-text syntax !alt text!url is not supported and renders literally, so keep images bare.

Lists

Unnumbered lists use “*”, numbered lists use “#”. Nesting is a matter of depth:

  1. numbered one
  2. numbered two
    1. nested under two
  3. numbered three

Inline markup works inside list items, as this item demonstrates with a link.

Blockquotes

A line beginning “bq.” becomes a blockquote. Ornaments inside are honored.

Every file dies. Not every file decays with style.

Line breaks

A single newline inside a paragraph is a soft break; a blank line starts a new paragraph. No double-space or backslash magic needed — just write.

Special characters

Ampersands, angle brackets, and quotes are escaped on output; UTF-8 passes through untouched. Ampersand: & — plus the museum pieces óöüäß survive verbatim.

There is no escape hatch. A backslash does not neutralize markup — \not bold\ keeps the backslashes and still renders bold. For a literal ampersand write & in the source; for a literal angle bracket write < or >. The entities pass through and display as their characters.

Raw HTML

Where Markdown passes raw HTML through verbatim, Textile escapes it. No <b>smuggled tags</b> in textile tombs — the angle brackets come out as text, not markup. If you need raw HTML, the page belongs on the Markdown side of the cemetery.

The literal boundary

Textile markup Oliver does not implement renders as literal text — never a crash, never a guess. These are the known fallbacks:

code blocks (bc. and bc..)

preformatted blocks
_.tables _.with _.pipes

1 footnotes (and their 1 references)

— horizontal rules

dl. definition lists

{styled} percent spans (the % wrapper survives only as a bare span, attributes lost) and notextile. blocks

If you need a table or a code block, write the page in Markdown — GFM tables and fenced code are first-class there (see the Oliver Renderer Contract for the Markdown surface). The two formats coexist per directory; only the basenames must not collide: foo.md and foo.textile in the same directory abort the render rather than fight over one foo.html tombstone.