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
```yaml
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:
```yaml
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:
```yaml
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)
```yaml
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:
```yaml
extra:
  status:
    new: Recently added
    deprecated: Legacy
```

### 2c. Search boost
Boost important entry-point pages so they rank higher:
```yaml
---
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`:
```markdown
*[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`:
```markdown
---
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:
```html
{% 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](https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/)
- [Setting up navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/)
- [Page status](https://squidfunk.github.io/mkdocs-material/reference/index/#setting-the-page-status)
- [Search boosting](https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-boosting)
- [Abbreviations](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)
- [Cookie consent](https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent)
- [Custom 404](https://www.mkdocs.org/user-guide/custom-themes/#custom-theme)
- [Announcement bar](https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#announcement-bar)