Skip to content

Building & Deploying

The EPMware documentation sites are deployed to GitHub Pages using GitHub Actions. This section covers the local preview workflow, the deployment pipeline, and how to manage releases.

Local Preview

Always preview changes locally before pushing to GitHub.

Running the Local Server

From the project root directory (where mkdocs.yml is located):

mkdocs serve

This starts a local development server at http://127.0.0.1:8000/. The server watches for file changes and automatically rebuilds the site when you save a file.

What to Check During Preview

  1. Navigation — Verify new or changed pages appear in the sidebar.
  2. Links — Click all links you added or modified. Check for 404 errors.
  3. Images — Confirm images display correctly and captions are positioned properly.
  4. Formatting — Check that admonitions, tables, code blocks, and icons render as expected.
  5. Search — Test that new content is findable via the search bar.
  6. Dark mode — Toggle dark mode and verify content is readable.

Common Local Server Issues

If mkdocs serve fails to start:

  • YAML syntax error — Check for tabs (use spaces), unclosed quotes, or colons in unquoted values. The error message will indicate the line number.
  • Missing plugin — If you see an error about a missing plugin (e.g., glightbox), install it: pip install mkdocs-glightbox.
  • Port already in use — If port 8000 is busy, specify a different port: mkdocs serve -a localhost:8001.

Deployment Pipeline

How GitHub Actions Deployment Works

When you push changes to the main branch on GitHub, a GitHub Actions workflow automatically:

  1. Checks out the repository.
  2. Sets up Python and installs MkDocs and required plugins.
  3. Runs mkdocs build to generate the static site.
  4. Deploys the built site to the gh-pages branch.
  5. GitHub Pages serves the site from the gh-pages branch.

The workflow file is located at .github/workflows/deploy.yml.

Pushing Changes

The standard workflow for deploying updates:

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Update configuration section with new application properties"

# Push to main branch
git push origin main

GitHub Actions will trigger automatically. You can monitor the build status on the GitHub repository's Actions tab.

Verifying Deployment

After pushing:

  1. Go to the GitHub repository → Actions tab.
  2. Find the latest workflow run and confirm it completed successfully (green checkmark).
  3. Visit the live site URL to verify the changes are published.
  4. Allow a few minutes for GitHub Pages to update its cache.

Deployment Timing

It typically takes 1–3 minutes for the GitHub Actions workflow to complete. After that, GitHub Pages may take an additional minute or two to propagate the changes.

GitHub Actions Workflow

The deployment workflow file (.github/workflows/deploy.yml) defines the CI/CD pipeline:

name: Deploy MkDocs
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material mkdocs-glightbox
      - run: mkdocs gh-deploy --force

GitHub Actions Deprecation Warnings

You may see deprecation warnings in the Actions logs for older action versions (e.g., actions/checkout@v3). These are upstream issues — update the version numbers in deploy.yml when new versions are released (e.g., change @v3 to @v4). The warnings do not prevent deployment but should be addressed to avoid future breakage.

Modifying the Workflow

If you add new MkDocs plugins that need to be installed, update the pip install line:

- run: pip install mkdocs-material mkdocs-glightbox new-plugin-name

Building Without Deploying

To generate the static site files locally without deploying:

mkdocs build

This creates a site/ directory containing the complete static site. You can open site/index.html in a browser to view it, or use the contents for manual deployment.

Multiple Documentation Sites

EPMware maintains multiple documentation sites (e.g., Administrator's Guide, User's Guide). Each site is a separate GitHub repository with its own mkdocs.yml, docs/ directory, and GitHub Actions workflow. The sites share the same theme configuration and custom CSS for a consistent look and feel.

When making styling or structural changes that should apply across all sites, update each site's custom.css and mkdocs.yml individually to keep them in sync.