Skip to content

EPMware MkDocs Maintenance Guide

This guide provides procedures for maintaining and updating the EPMware documentation sites built with MkDocs and the Material theme. It covers day-to-day content editing, link management, image handling, and deployment — along with a troubleshooting section for resolving common issues.

About the EPMware Documentation Sites

EPMware maintains documentation sites using MkDocs with the Material for MkDocs theme, deployed to GitHub Pages via GitHub Actions. The primary documentation sites include the Administrator's Guide and the User's Guide.

Each site follows the same structure, styling, and conventions documented in this guide.

Who Should Use This Guide

This guide is intended for staff who need to update, maintain, or troubleshoot the EPMware MkDocs documentation sites. It assumes basic familiarity with text editing and file management but does not require deep technical knowledge of MkDocs or Python.

Key Topics

  • Maintenance Guide — Step-by-step procedures for editing content, managing links, adding images, updating configuration, and deploying changes
  • Troubleshooting — Solutions for common issues including broken links, build errors, and formatting problems
  • Quick Reference — Cheat sheets for markdown syntax, link paths, and frequently used patterns

Prerequisites

Before working with the documentation sites, ensure you have:

  • Access to the GitHub repository for the documentation site
  • A local copy of the repository synced via Dropbox or Git
  • Python installed (for running mkdocs serve locally)
  • MkDocs and the Material theme installed (pip install mkdocs-material)

Always Preview Locally

Before pushing any changes, run mkdocs serve from the project root and verify your changes at http://127.0.0.1:8000/ in your browser. This catches broken links, formatting issues, and YAML errors before they reach the live site.

Quick Start

If you need to make a simple content update, the basic workflow is:

  1. Edit the appropriate .md file in the docs/ folder.
  2. Run mkdocs serve to preview your changes locally.
  3. Commit and push your changes to GitHub.
  4. GitHub Actions will automatically build and deploy the updated site.

For detailed procedures, start with the Maintenance Guide.