81 lines
1.6 KiB
Markdown
81 lines
1.6 KiB
Markdown
|
# 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.
|