Skip to content

Contributing to Documentation

This guide explains how to contribute to AME's internal documentation using Material for MkDocs, a modern static site generator built on top of MkDocs.

1. Clone the Documentation Repository

Make sure you are a member of the AME GitHub Organization and have access to the documentation repository.

git clone https://github.com/AME-Consulting-Ltd/ame-docs.git
cd ame-docs

2. Set Up Your Environment

Install Python (latest version) and then set up a virtual environment:

python -m venv venv
source venv/Scripts/activate  # Windows Git Bash
# or
venv\Scripts\activate.bat   # Command Prompt

Install MkDocs and the Material theme:

pip install mkdocs-material

Optionally, install live reload plugins:

pip install mkdocs-literate-nav mkdocs-glightbox

3. Preview the Docs Locally

From the root of the project, run:

mkdocs serve

Visit the local site at: http://127.0.0.1:8000

4. Adding Content

All documentation pages are located inside the docs/ directory.

  • Use .md (Markdown) files for each page.
  • Organize sections in folders like:
  • docs/ame-timesheets/
  • docs/onboarding/
  • docs/how-to/

Edit the navigation structure in mkdocs.yml to reflect new or moved pages.

Example:

nav:
  - Home: index.md
  - Onboarding:
      - Environment Setup: onboarding/setup.md

5. Style & Formatting Guidelines

  • Use level 1 headings (#) only for page titles
  • Keep page titles consistent with mkdocs.yml
  • Favor clarity over cleverness
  • Use lists, bullet points, and code blocks where helpful
  • Follow Material for MkDocs syntax

6. Building for Production

To generate a static site:

mkdocs build

The final site will be generated in the site/ folder.

7. Deployment

Our GitHub Actions workflow automatically deploys on every push to main.

Nothing to do manually — just commit your changes, push, and GitHub Pages will update.

If needed for manual deployment:

mkdocs gh-deploy --force

Helpful Resources

  • MkDocs: https://www.mkdocs.org/
  • Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
  • Markdown Cheatsheet: https://www.markdownguide.org/basic-syntax/

Please reach out to the maintainers if you have questions or want help making your first contribution.