Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.
The code is in the doctools/ directory, which uses the lazylex/ library.
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
Most docs start with something like this:
--- in_progress: yes default_highlighter: oil-sh --- My Title ======== Hello
The "front matter" between
--- lines is metadata for rendering the doc.
Github's web UI understands and renders it.
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.
Insert this into the doc
<div id="toc"> </div>
and it will be expanded into a table of contents derived from
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>
$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:
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 spaces.
Again see doc-plugins.md for examples.
This is done with