maud/docs
2024-10-29 18:31:39 -03:00
..
content Undo autoformatting change 2024-10-29 18:31:39 -03:00
src Fix syntax highlighting for no_run blocks () 2024-08-22 05:43:22 +00:00
Cargo.lock Switch to use Comrak for syntax highlighting () 2024-08-22 12:58:41 +10:00
Cargo.toml Switch to use Comrak for syntax highlighting () 2024-08-22 12:58:41 +10:00
Makefile Fix docs version indicator to include unannotated tags () 2021-10-01 12:58:15 +00:00
README.md Add a style guide for the docs () 2021-11-29 11:06:56 +00:00
styles.css Remove horizontal body padding in docs site 2021-11-01 16:52:55 +11:00
watch.sh In watch script, exclude built files from watch 2019-03-24 14:56:44 +13:00

Documentation

This directory contains the documentation for Maud.

It is hosted at https://maud.lambda.xyz.

Build

Build the documentation:

make

The built files will be placed in site/.

You can also delete the build artifacts with:

make clean

Style

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.

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:

-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 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.