2019-03-30 16:17:49 +13:00
|
|
|
|
# Documentation
|
|
|
|
|
|
|
|
|
|
This directory contains the documentation for Maud.
|
|
|
|
|
|
|
|
|
|
## Build
|
|
|
|
|
|
|
|
|
|
Build the documentation:
|
|
|
|
|
|
|
|
|
|
make
|
|
|
|
|
|
|
|
|
|
The built files will be placed in `site/`.
|
|
|
|
|
|
|
|
|
|
You can also delete the build artifacts with:
|
|
|
|
|
|
|
|
|
|
make clean
|
|
|
|
|
|
|
|
|
|
## Watch
|
|
|
|
|
|
|
|
|
|
To ease editing,
|
|
|
|
|
there is a `./watch.sh` script
|
|
|
|
|
that starts a web server
|
|
|
|
|
and rebuilds the site
|
|
|
|
|
on every change.
|
|
|
|
|
|
|
|
|
|
The script uses Python 3 and [entr],
|
|
|
|
|
but feel free to adapt it
|
|
|
|
|
to your environment.
|
|
|
|
|
|
|
|
|
|
[entr]: http://eradman.com/entrproject/
|
|
|
|
|
|
|
|
|
|
## Add a new page
|
|
|
|
|
|
|
|
|
|
The list of pages to be built
|
|
|
|
|
is defined by the `slugs` variable
|
|
|
|
|
in the Makefile.
|
|
|
|
|
|
|
|
|
|
To add a new page,
|
|
|
|
|
create a Markdown file in `content/`
|
|
|
|
|
and add its name
|
|
|
|
|
(excluding the `.md`)
|
|
|
|
|
to `slugs`:
|
|
|
|
|
|
|
|
|
|
```diff
|
|
|
|
|
-slugs := index getting-started basic-syntax partials ...
|
|
|
|
|
+slugs := index getting-started basic-syntax my-awesome-new-page partials ...
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The order of the names in `slugs`
|
|
|
|
|
determines the order of entries
|
|
|
|
|
in the table of contents.
|
|
|
|
|
|
|
|
|
|
Make sure that
|
|
|
|
|
your page starts with a heading
|
|
|
|
|
(e.g. `# My awesome new page`)
|
|
|
|
|
or it won't show up.
|
|
|
|
|
|
|
|
|
|
## The navigation cache (`nav.json`)
|
|
|
|
|
|
|
|
|
|
The site generator
|
|
|
|
|
constructs the table of contents dynamically
|
|
|
|
|
by reading each Markdown page
|
|
|
|
|
and extracting its heading.
|
|
|
|
|
This data is cached in `nav.json`.
|
|
|
|
|
|
|
|
|
|
You don't need to care about this file
|
|
|
|
|
most of the time,
|
|
|
|
|
but it might be useful to know about it
|
|
|
|
|
when hacking on the site generator itself.
|
|
|
|
|
|
|
|
|
|
## Deployment
|
|
|
|
|
|
2021-01-09 19:19:51 +13:00
|
|
|
|
The documentation is built
|
|
|
|
|
and uploaded to GitHub Pages
|
|
|
|
|
using [GitHub Actions][config].
|
|
|
|
|
|
|
|
|
|
The workflow is run automatically on a new release.
|
|
|
|
|
For changes not tied to a release (e.g. typo fixes),
|
|
|
|
|
a maintainer can trigger it manually –
|
|
|
|
|
please ask if you'd like this.
|
|
|
|
|
|
|
|
|
|
[config]: ../.github/workflows/publish-docs.yml
|