This directory contains the documentation for Maud.
It is hosted at https://maud.lambda.xyz.
Build the documentation:
make
The built files will be placed in site/.
You can also delete the build artifacts with:
make clean
- Be brief.
- Use semantic line breaks.
- American spelling.
- Parentheticals should use spaced en dashes – like this – not em dashes.
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.
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:
-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 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.
The documentation is built and uploaded to GitHub Pages using GitHub Actions.
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.