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).