Skip to content

Guide — Getting started & examples

Welcome to the Guide section. This page provides a short roadmap and example pages to get you up and running with the project documentation. Use the links below to navigate to the detailed pages.

How to use this guide

This guide is organized so you can quickly find: - A minimal, practical setup to run the project locally. - Common commands and environment variables you will need. - Tips for writing and organizing docs that work well with Material and awesome-pages.

Start with getting-started.md if you are new to the project. Jump to advanced.md for architecture notes and recommended practices.

Getting started (high level)

The getting-started.md page contains step-by-step instructions to: 1. Install prerequisites. 2. Clone the repository. 3. Build / run the project locally. 4. Run tests.

Example (commands shown here are illustrative; see getting-started.md for real commands):

# Clone the repo
git clone https://github.com/your_org/your_repo.git

# Change into the project directory and install dependencies (example)
cd your_repo
pip install -r requirements.txt   # or `npm install` / `bundle install`

# Run the application
./run-local.sh                    # or `make dev`, `npm start`, etc.

Advanced (what you'll find in advanced.md)

The advanced.md page includes: - Architectural overview and diagrams (if present). - Coding conventions and design patterns used. - Performance tips and profiling commands. - Deployment checklist and CI/CD notes. - Troubleshooting common problems and log locations.

pages.yml example

When using the awesome-pages plugin you control page order and grouping by adding a .pages.yml file to a directory. Put the file in the directory where you want to control ordering.

Example .pages.yml for this guide directory (place at wiki/docs/guide/.pages.yml):

# .pages.yml — order pages inside the guide folder
- index.md
- getting-started.md
- advanced.md

A top-level .pages.yml (in wiki/docs/.pages.yml) might look like:

- index.md
- guide:
  - index.md
  - getting-started.md
  - advanced.md
- reference.md
- changelog.md

awesome-pages will respect this order when building the navigation.

Recommendations for writing docs

  • Keep pages short and focused — prefer multiple small pages over one very long page.
  • Use relative links like guide/getting-started.md or just getting-started.md when linking within the same folder.
  • Add front-matter or headings to improve search indexing and site navigation.
  • Use the Material theme features (e.g., navigation.indexes) to improve discoverability — configured in wiki/mkdocs.yml.
  • When adding new sections, also update .pages.yml to ensure the navigation order is correct for readers.

Next steps (suggested)

  1. Open wiki/docs/guide/getting-started.md and follow the setup instructions.
  2. Add any missing example files:
  3. wiki/docs/guide/getting-started.md
  4. wiki/docs/guide/advanced.md
  5. If you want a custom top-level navigation, create or update wiki/docs/.pages.yml.

  6. Verify locally with:

    Build and serve locally with MkDocs

    mkdocs serve

  7. Commit your changes and push to your repository.

If you'd like, I can also: - Create example getting-started.md and advanced.md content (with full commands and checks). - Generate a top-level .pages.yml tuned to your repo structure. - Adjust wiki/mkdocs.yml values (site_url, repo_url) and show recommended CI steps for building the site.