Maintenance Guide

This section covers the day-to-day procedures for updating and maintaining the EPMware MkDocs documentation sites. Each topic below addresses a specific area of the documentation workflow.

Overview

Maintaining the documentation involves working with several types of files, each with its own conventions and potential pitfalls. Understanding how these files interact is critical to making clean updates that don't break the site.

The documentation sites are built from these core components:

• Markdown files (.md) — The actual page content, located under docs/
• mkdocs.yml — The site configuration file that defines navigation, theme settings, plugins, and extensions
• custom.css — Custom styling overrides for the Material theme
• Image files — Screenshots and diagrams stored under docs/assets/images/
• GitHub Actions workflow — The CI/CD pipeline that builds and deploys the site

Maintenance Topics

• File Structure & Organization — Understand the project directory layout and where files belong
• Editing Markdown Content — How to update page content while following EPMware conventions
• Managing Links & Cross-References — The most common source of issues; covers markdown links, HTML links, relative paths, and anchor references
• Managing Images — Adding, replacing, and organizing screenshots
• Editing mkdocs.yml — Updating navigation, adding pages, and configuring extensions
• Custom CSS Styling — Making style changes without breaking existing formatting
• Building & Deploying — Local previewing, GitHub Actions, and deployment workflow

Links Are the #1 Source of Problems

The most frequent issues encountered during documentation maintenance involve broken links. Before making any link changes, read the Managing Links & Cross-References section carefully. Understanding the difference between markdown links and HTML links in MkDocs will save you significant debugging time.