# Wiki / Documentation (MkDocs)

This repository serves documentation (the project "wiki") via an MkDocs-built static site that is exposed behind the protected `/wiki/` route in the app.

Quick facts - Served path: `http://127.0.0.1:8000/wiki/` (protected; requires login) - Source files: `docs/` (Markdown source) - Built site: `site/` (static HTML generated by `mkdocs build`) - Config: `mkdocs.yml`

How the wiki is served - The Flask app serves the built site in `site/` at the `/wiki/` route. If you change source files under `docs/` you must rebuild with `mkdocs build` so the app serves the updated static files.

Edit & preview locally (recommended workflow) 1. Install dependencies (if not already installed): `bash python -m pip install --upgrade pip pip install mkdocs mkdocs-material` 2. Edit Markdown files under `docs/` (or add new pages and update `mkdocs.yml` nav). 3. Build & preview: `bash mkdocs serve -a 127.0.0.1:8000` Then visit `http://127.0.0.1:8000/` to preview while developing. To update the site served by the app, run: `bash mkdocs build` and commit the updated `site/` files if you want the app to serve the newest build.

Note about the app-protected wiki - The app redirects requests to `/wiki/` to the sign-in page if you are not authenticated; this is intentional for a protected internal wiki. - If the server redirects anonymous users, sign in (`/sign_in.html`, or use `init_db.py` seeded user). See `docs/dam_pro/getting_back.md` for more details.

GitHub Wiki vs MkDocs site - This project uses an MkDocs site (versioned alongside the repo), not the GitHub-provided "Wiki" (which is a separate Git repo `repo.wiki.git`). - Pros of the MkDocs approach: - Versioned and reviewed with PRs alongside code - Full control of styling and plugins (MkDocs Material, plugins) - Can be integrated into CI (build, link check, deploy) - Cons: - Must run `mkdocs build` to update the served static files (or set CI to auto-build)

Modern CMS options (if you want editable UI + Git-backed content) - Netlify CMS (Git-backed, easy to add to static sites) — good if you want non-technical editors to update Markdown content via a UI. - Forestry / TinaCMS / Sanity / Contentful — headless CMS options with richer editorial workflows and media management (usually paid for teams). - GitHub + Pull Requests (what we have): simpler, reviewable, and free. For a solo or small team this is usually sufficient.

Recommendations - If you prefer a UI for non-technical editors and want to keep the site static, set up Netlify CMS or TinaCMS and wire it to the `docs/` content. I can add a starter integration for MkDocs + Netlify CMS. - Otherwise, keep using `docs/` + `mkdocs build` and add a small CONTRIBUTING or CHANGELOG section with edit instructions (I included this file to start that effort).