maud/docs/README.md

81 lines
1.6 KiB
Markdown
Raw Normal View History

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
The documentation is automatically built
and uploaded to GitHub pages
on every commit to `master`.
However,
if you wish to deploy the docs manually,
then you can do that by running `./deploy.sh`.
You will need push access to the Maud repository
to do this.