Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

How We Build Oil's Documentation

  1. Write Markdown by hand, with optional "front matter".
  2. Render Markdown to HTML, and run the result through our own HTML filters.
  3. Publish static HTML to https://www.oilshell.org/.

The code is in the doctools/ directory, which uses the lazylex/ library.

Table of Contents
Quick Start
Front Matter and Title
Plugins That Transform HTML
Table of Contents
Link Shortcuts, e.g. $xref
Syntax Highlighting of Code Blocks
The Help Toolchain Renders to HTML and ANSI
Code Location

Quick Start

To build and preview this doc, run:

build/doc.sh split-and-render doc/doc-toolchain.md

Open the path in prints in your browser (_release/VERSION/doc/doc-toolchain.html).

Front Matter and Title

Most docs start with something like this:

in_progress: yes
default_highlighter: oil-sh

My Title


The "front matter" between --- lines is metadata for rendering the doc. Github's web UI understands and renders it.

Plugins That Transform HTML

We have some HTML plugins that make writing markdown easier. Note that CommonMark tightens up the rules for embedding HTML in Markdown, and that is very useful.

Table of Contents

Insert this into the doc

<div id="toc">

and it will be expanded into a table of contents derived from h2 and h3 tags.

Link Shortcuts, e.g. $xref

Here's an example of how it works. This Markdown:

The [GNU bash shell]($xref:bash)

is translated to HTML by CommonMark:

The <a href="$xref:bash">GNU bash shell</a>

Our $xref: plugin expands it to:

The <a href="/cross-ref.html#bash">GNU bash shell</a>

If the argument is omitted, then the anchor text is used. So you can just write:


and it will become:

The <a href="/cross-ref.html#bash">bash</a>

List of plugins:

See the raw and rendered versions of this doc for more:

Syntax Highlighting of Code Blocks

Use Markdown's fenced code blocks like this:

``` sh-prompt
oil$ var x = 'hello world'
oil$ echo $x
hello world

Or you can set default_highlighter for blocks indented by 4 sapces.

Again see doc-plugins.md for examples.

The Help Toolchain Renders to HTML and ANSI

TODO: Describe how this works. We have a plugin for the table of contents.

It's published to the web as well as underlying the help builtin. TODO: Render to ANSI.

We also split {osh,oil}-help.md into "cards".

Table of contents: {osh,oil}-help-topics.md.

Code Location

Generated on Sat Jan 23 00:06:31 PST 2021