changemaker.lite/mkdocs/DOCS_NEXT_STEPS.md

Documentation Next Steps — Editorial & Material Theme Enhancement Plan

Date: 2026-03-22 Branch: v2 Status: Planning → Execution

---

Executive Summary

The MkDocs documentation site is comprehensive (70+ pages, all with proper frontmatter, no stubs) and already uses many Material theme features well (grid cards, admonitions, code copy, mermaid diagrams, social cards, blog plugin, dark/light toggle). This plan focuses on activating dormant Material theme capabilities and editorial polish to take the docs from "complete" to "professional-grade."

---

Step 1: mkdocs.yml Configuration Hardening

Goal: Enable Material theme features that are available but not configured.

1a. Add missing theme features

features:
  # Already enabled (keep):
  - announce.dismiss
  - content.action.edit
  - content.action.view
  - content.code.annotate
  - content.code.copy
  - content.tooltips
  - navigation.footer
  - navigation.indexes
  - navigation.path
  - navigation.prune
  - navigation.tabs
  - navigation.tabs.sticky
  - navigation.top
  - navigation.tracking
  - search.highlight
  - search.share
  - search.suggest
  - toc.follow

  # ADD these:
  - navigation.instant          # SPA-like navigation (no full page reload)
  - navigation.instant.prefetch # Prefetch pages on hover
  - navigation.instant.progress # Show loading progress bar
  - content.code.select         # Line selection in code blocks
  - content.tabs.link           # Linked content tabs (sync across page)

1b. Fix consent banner

The copyright references #__consent but no consent config exists. Add:

extra:
  consent:
    title: Cookie consent
    description: >
      We use cookies to recognize your repeated visits and preferences,
      as well as to measure the effectiveness of our documentation.
      With your consent, you help us improve.
    actions:
      - accept
      - reject
      - manage

1c. Fix copyright year

Change 2024 → 2024–2026 in the copyright line.

1d. Fix edit_uri branch

Change edit_uri: src/branch/main/mkdocs/docs → edit_uri: src/branch/v2/mkdocs/docs

1e. Add abbreviations snippets

Create docs/includes/abbreviations.md and reference via snippets:

markdown_extensions:
  - pymdownx.snippets:
      auto_append:
        - includes/abbreviations.md

Common abbreviations: API, JWT, RBAC, CSV, ORM, SMTP, CORS, SSL, TLS, DNS, CRUD, SSO, SPA, CLI, GUI, QR, GPS, GDPR, CDN, VPS, CGNAT, NAR, CRM, OG, DDoS, SSE, UUID, FOSS, HSTS, CSP

1f. Add privacy plugin (optional, external resource proxying)

plugins:
  - privacy

---

Step 2: Page-Level Metadata Enhancement

Goal: Add tags, status, and search.boost metadata to every page.

2a. Tags

The tags plugin is loaded but zero pages use tags. Add contextually appropriate tags to every page. Example tag taxonomy:

• Audience: admin, volunteer, user, operator, developer
• Module: influence, map, media, payments, broadcast, social
• Type: guide, reference, tutorial, concept, troubleshooting
• Feature: campaigns, canvassing, shifts, gallery, landing-pages, newsletter, sms, chat, events

2b. Status badges

Material supports status: new and status: deprecated on pages, shown as badges in the nav sidebar. Apply:

• status: new — Recent features (Gallery Ads, People CRM, Achievements, Social Calendar, CrowdSec, SMS, Docs Comments, Payments)
• status: deprecated — Legacy/archival content if any

Requires adding to extra: in mkdocs.yml:

extra:
  status:
    new: Recently added
    deprecated: Legacy

2c. Search boost

Boost important entry-point pages so they rank higher:

---
search:
  boost: 2
---

Apply to: Getting Started index, Installation, First Steps, Features at a Glance, FAQ/Troubleshooting.

---

Step 3: Abbreviations Glossary

Goal: Create a shared abbreviations file so that hovering over acronyms shows their meaning.

Create mkdocs/docs/includes/abbreviations.md:

*[API]: Application Programming Interface
*[JWT]: JSON Web Token
*[RBAC]: Role-Based Access Control
*[CORS]: Cross-Origin Resource Sharing
*[SMTP]: Simple Mail Transfer Protocol
*[CSV]: Comma-Separated Values
*[ORM]: Object-Relational Mapping
*[SSL]: Secure Sockets Layer
*[TLS]: Transport Layer Security
*[DNS]: Domain Name System
*[CRUD]: Create, Read, Update, Delete
*[SSO]: Single Sign-On
*[SPA]: Single Page Application
*[CLI]: Command Line Interface
*[GUI]: Graphical User Interface
*[QR]: Quick Response (code)
*[GPS]: Global Positioning System
*[GDPR]: General Data Protection Regulation
*[CDN]: Content Delivery Network
*[VPS]: Virtual Private Server
*[CGNAT]: Carrier-Grade Network Address Translation
*[NAR]: National Address Register
*[CRM]: Customer Relationship Management
*[OG]: Open Graph
*[DDoS]: Distributed Denial of Service
*[SSE]: Server-Sent Events
*[UUID]: Universally Unique Identifier
*[FOSS]: Free and Open Source Software
*[HSTS]: HTTP Strict Transport Security
*[CSP]: Content Security Policy
*[BullMQ]: Bull Message Queue
*[FFprobe]: FFmpeg Probe (media metadata tool)
*[FFmpeg]: Fast Forward Moving Picture Experts Group
*[XMPP]: Extensible Messaging and Presence Protocol

---

Step 4: Custom 404 Page

Goal: Branded 404 page instead of browser default.

Create mkdocs/docs/404.md:

---
template: main.html
title: Page Not Found
hide:
  - navigation
  - toc
  - footer
search:
  exclude: true
---

# Page Not Found

The page you're looking for doesn't exist or has been moved.

[Go to Documentation Home](docs/index.md){ .md-button .md-button--primary }
[Search](docs/index.md){ .md-button }

---

Step 5: Content Fixes — Broken Links & Stale Warnings

Goal: Fix all broken links, placeholder content, and stale warnings.

5a. Fix broken "Coming soon" links

• docs/index.md: Monitoring card links to ../blog/index.md → link to admin/services/monitoring.md
• docs/index.md: Contributing card links to ../blog/index.md → create a contributing stub or remove placeholder

5b. Fix Architecture page

Remove "Under Construction" admonition. Flesh out with:

• Mermaid system diagram
• Database entity relationship summary
• Authentication flow (already started)
• Request lifecycle

5c. Fix Troubleshooting page

Remove "Under Construction" admonition. Add more entries from CLAUDE.md and production experience.

5d. Fix Admin Guide roles table

Only lists 5 roles but there are 11. Add missing roles: BROADCAST_ADMIN, CONTENT_ADMIN, MEDIA_ADMIN, PAYMENTS_ADMIN, EVENTS_ADMIN, SOCIAL_ADMIN

5e. Social icons semantic fix

GitHub icon links to Gitea — change icon to fontawesome/brands/gitea or simple/gitea if available, or use a generic fontawesome/solid/code-branch.

---

Step 6: Cleanup Test/Orphan Files

Goal: Remove files that shouldn't be in the docs directory.

• docs/test.md (41KB test file)
• docs/test-page.md
• docs/testing.md
• docs/lander.md (override template pointer — keep if used by index.md)
• docs/main.md (override template pointer — keep if used)

Verify lander.md and main.md are still needed by checking if any page uses template: lander.html or template: main.html.

---

Step 7: Announcement Bar

Goal: Use Material's announcement bar for version/status info.

Create mkdocs/docs/overrides/main.html addition (or modify existing) with announcement block:

{% block announce %}
  Changemaker Lite v2 — <a href="docs/getting-started/index.md">Get started in 5 minutes</a>
{% endblock %}

Note: The existing main.html override is 35KB — check if it already has an announce block before modifying.

---

Step 8: Blog Seeding

Goal: Create 1–2 initial blog posts so the blog section isn't empty.

Suggested posts:

1. "Introducing Changemaker Lite v2" — Overview of the rebuild, what's new, philosophy
2. "Why Self-Hosted Campaign Tools Matter in 2026" — Draws from the Philosophy page

---

Step 9: Screenshot Audit

Goal: Verify all ![...](../../assets/images/screenshots/...) references resolve to actual files. Take new screenshots with Playwright where missing or outdated.

Pages referencing screenshots:

• Getting Started index (dashboard.png)
• First Steps (login.png, dashboard.png, settings-organization.png, campaigns.png, locations.png, shifts.png)
• Dashboard (dashboard.png)
• People & Access (users.png)
• Settings (settings.png)
• Campaigns (campaigns.png)

---

Priority Order

Priority	Step	Impact	Effort
P0	Step 1 (mkdocs.yml fixes)	High — broken consent, wrong branch, missing SPA nav	Low
P0	Step 5 (broken links/content)	High — broken UX	Medium
P0	Step 6 (cleanup test files)	Medium — professional appearance	Low
P1	Step 3 (abbreviations)	Medium — reader comprehension	Low
P1	Step 4 (404 page)	Medium — UX polish	Low
P1	Step 2 (tags/status/boost)	Medium — discoverability	Medium-High
P2	Step 7 (announcement bar)	Low-Medium — branding	Low
P2	Step 8 (blog seeding)	Low — completeness	Medium
P2	Step 9 (screenshot audit)	Medium — visual credibility	High

---

Material Theme Reference

Key Material docs for implementers:

• Setting up tags
• Setting up navigation
• Page status
• Search boosting
• Abbreviations
• Cookie consent
• Custom 404
• Announcement bar