Skip to content

docs/ — Documentation

The documentation for GGIS is built with MkDocs using the Material theme. The source lives in the docs/ directory of the repository.

Directory Structure

docs/
├── src/                        # Markdown source files
│   ├── index.md                # Home page
│   ├── administration/         # Admin guides
│   ├── developer/              # Developer guides (you are here)
│   └── harvester/              # Harvester integration guides
├── src/_assets/                # Shared CSS and images
├── mkdocs-base.yml             # Shared MkDocs config (nav, extensions)
├── mkdocs-html.yml             # HTML build config (inherits base)
├── mkdocs.yml                  # Default config used by mkdocs serve
├── build-docs-html.sh          # Script to build the HTML site
├── Makefile                    # Developer shortcut commands
└── requirements.txt            # Python dependencies for building docs

Running Locally

Install dependencies and start the live-reload server:

cd docs
pip install -r requirements.txt
mkdocs serve

The site will be available at http://localhost:8000.

Building

Build the static HTML site:

cd docs
bash build-docs-html.sh

Output goes to docs/site/. The CI pipeline publishes this to GitHub Pages automatically on every push to main.

Adding a Page

  1. Create a new .md file under the relevant src/ subdirectory.
  2. Add the frontmatter block (copy from an existing file — title, summary, author, date, copyright, license).
  3. Register the page in the nav: section of mkdocs-base.yml.

Navigation is defined in docs/mkdocs-base.yml under the nav: key.