Why Sponsor Oils? | source | all docs for version 0.22.0 | all versions | oilshell.org
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
(_release/VERSION/doc/doc-toolchain.html).
Most docs start with something like this:
---
in_progress: yes
default_highlighter: oils-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 h2 and h3
tags.
$xrefHere'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:
[bash][]
and it will become:
The <a href="/cross-ref.html#bash">bash</a>
List of plugins:
$xref:bash expands to /cross-ref.html#bash (shown above)$blog-tag:oil-release expands to /blog/tags.html#oil-release$oils-srcSee the raw and rendered versions of this doc for more:
Use Markdown's fenced code blocks like this:
``` sh-prompt
ysh$ var x = 'hello world'
ysh$ 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 doctools/