| 1 | ---
|
| 2 | in_progress: yes
|
| 3 | ---
|
| 4 |
|
| 5 | How We Build Oils Documentation
|
| 6 | ================================
|
| 7 |
|
| 8 | 1. Write Markdown by hand, with optional "front matter".
|
| 9 | 2. Render Markdown to HTML, and run the result through our own HTML filters.
|
| 10 | 3. Publish static HTML to <https://www.oilshell.org/>.
|
| 11 |
|
| 12 | The code is in the [doctools/]($oils-src) directory, which uses the
|
| 13 | [lazylex/]($oils-src) library.
|
| 14 |
|
| 15 | <div id="toc">
|
| 16 | </div>
|
| 17 |
|
| 18 | ## Quick Start
|
| 19 |
|
| 20 | To build and preview this doc, run:
|
| 21 |
|
| 22 | build/doc.sh split-and-render doc/doc-toolchain.md
|
| 23 |
|
| 24 | Open the path in prints in your browser
|
| 25 | (`_release/VERSION/doc/doc-toolchain.html`).
|
| 26 |
|
| 27 | ## Front Matter and Title
|
| 28 |
|
| 29 | Most docs start with something like this:
|
| 30 |
|
| 31 | ---
|
| 32 | in_progress: yes
|
| 33 | default_highlighter: oils-sh
|
| 34 | ---
|
| 35 |
|
| 36 | My Title
|
| 37 | ========
|
| 38 |
|
| 39 | Hello
|
| 40 |
|
| 41 | The "front matter" between `---` lines is metadata for rendering the doc.
|
| 42 | Github's web UI understands and renders it.
|
| 43 |
|
| 44 | ## Plugins That Transform HTML
|
| 45 |
|
| 46 | We have some HTML plugins that make writing **markdown** easier.
|
| 47 | Note that [CommonMark][] tightens up the rules for embedding HTML in Markdown,
|
| 48 | and that is very useful.
|
| 49 |
|
| 50 | [CommonMark]: https://www.oilshell.org/blog/2018/02/14.html
|
| 51 |
|
| 52 | ### Table of Contents
|
| 53 |
|
| 54 | Insert this into the doc
|
| 55 |
|
| 56 | <div id="toc">
|
| 57 | </div>
|
| 58 |
|
| 59 | and it will be expanded into a table of contents derived from `h2` and `h3`
|
| 60 | tags.
|
| 61 |
|
| 62 | ### Link Shortcuts, e.g. `$xref`
|
| 63 |
|
| 64 | Here's an example of how it works. This Markdown:
|
| 65 |
|
| 66 | The [GNU bash shell]($xref:bash)
|
| 67 |
|
| 68 | is translated to HTML by [CommonMark][]:
|
| 69 |
|
| 70 | The <a href="$xref:bash">GNU bash shell</a>
|
| 71 |
|
| 72 | Our `$xref:` plugin expands it to:
|
| 73 |
|
| 74 | The <a href="/cross-ref.html#bash">GNU bash shell</a>
|
| 75 |
|
| 76 | If the argument is omitted, then the **anchor text** is used. So you can just write:
|
| 77 |
|
| 78 | [bash][]
|
| 79 |
|
| 80 | and it will become:
|
| 81 |
|
| 82 | The <a href="/cross-ref.html#bash">bash</a>
|
| 83 |
|
| 84 | List of plugins:
|
| 85 |
|
| 86 | - `$xref:bash` expands to `/cross-ref.html#bash` (shown above)
|
| 87 | - `$blog-tag:oil-release` expands to `/blog/tags.html#oil-release`
|
| 88 | - `$oils-src`
|
| 89 |
|
| 90 | See the raw and rendered versions of this doc for more:
|
| 91 |
|
| 92 | - [doc-plugins.md][]
|
| 93 | - [doc-plugins.html](doc-plugins.html)
|
| 94 |
|
| 95 | [doc-plugins.md]: $oils-src:doc/doc-plugins.md
|
| 96 |
|
| 97 | ### Syntax Highlighting of Code Blocks
|
| 98 |
|
| 99 | Use Markdown's fenced code blocks like this:
|
| 100 |
|
| 101 | ``` sh-prompt
|
| 102 | ysh$ var x = 'hello world'
|
| 103 | ysh$ echo $x
|
| 104 | hello world
|
| 105 | ```
|
| 106 |
|
| 107 | Or you can set `default_highlighter` for blocks indented by 4 spaces.
|
| 108 |
|
| 109 | Again see [doc-plugins.md][] for examples.
|
| 110 |
|
| 111 | ## The Help Toolchain Renders to HTML and ANSI
|
| 112 |
|
| 113 | This is done with `doctools/`
|
| 114 |
|
| 115 | ## Code Location
|
| 116 |
|
| 117 | - [build/doc.sh]($oils-src) drives the tools in [doctools/]($oils-src).
|
| 118 | - Markdown files are in [doc/]($oils-src).
|
| 119 |
|
| 120 |
|