Otter Wiki

Otter Wiki is a lightweight, Python‑based wiki engine that marries the simplicity of Markdown with the robustness of Git for version control. Built on Flask, it exposes a minimal REST‑like interface that can be consumed by external tools while still offering an intuitive web UI for end users. The core idea is to treat every page as a plain Markdown file stored in a Git repository, allowing developers to leverage existing Git tooling for backups, branching, and collaboration. The application ships with an experimental HTTP server that exposes the underlying Git repo, enabling developers to clone or push changes directly from their local machines.

Architecture & Technical Stack

• Language & Framework: Python 3.10+ with the Flask microframework, keeping runtime footprint small while enabling easy extension via Flask extensions or custom blueprints.
• Frontend: Halfmoon CSS provides a clean, responsive UI with dark‑mode support; CodeMirror powers the Markdown editor and offers syntax highlighting for tables, footnotes, mermaid diagrams, and custom block types.
• Storage: A Git repository on the host filesystem (or a mounted volume) stores all page files and history. The repo can be hosted on any Git server or accessed via the built‑in HTTP server, giving developers full control over backup and replication strategies.
• Authentication: Flask‑Login is used for session management; the auth system supports self‑registration, password recovery, and role‑based access (admin vs. user).

Core Capabilities & APIs

• Page CRUD: Create, read, update, delete pages via the web UI; each operation commits a new Git revision.
• History & Diff: Full changelog per page, with side‑by‑side diffs rendered in the browser.
• Attachments: Binary files can be uploaded and linked from Markdown using a simple syntax; they are stored alongside the repo.
• Extended Markdown: Built‑in support for tables, footnotes, alerts, mermaid diagrams, and custom block types without requiring external plugins.
• Git HTTP Server: Exposes the repository over HTTP(S), enabling git clone, pull, and push from any client.
• Webhooks & API Hooks: While not a full REST API, the application exposes internal Flask endpoints that can be used by plugins or external services to trigger actions on page changes.

Deployment & Infrastructure

Otter Wiki is intentionally container‑friendly. The official Docker image (redimp/otterwiki) runs on a single container exposing port 80, with data persisted in a bind‑mounted volume (/app-data). For production, reverse proxies (nginx, Apache, Caddy) can be configured to provide HTTPS termination and domain routing. The Git HTTP server can be exposed behind the same proxy, allowing developers to treat the wiki as a fully fledged Git repository. Horizontal scaling is possible by running multiple read‑only replicas behind a load balancer, though the current design assumes a single writer due to Git’s file‑based locking.

Integration & Extensibility

• Plugin System: The codebase is modular; developers can add Flask blueprints to extend functionality (e.g., integrate with external auth providers or CI/CD pipelines).
• Customization: Themes can be swapped by replacing Halfmoon CSS files; the Markdown renderer is pluggable, so custom extensions (e.g., LaTeX support) can be added.
• Webhooks: External services can subscribe to page‑change events via HTTP callbacks, enabling automated documentation builds or notifications.
• API Access: Although not a full GraphQL/REST API, the internal Flask routes can be exposed or wrapped to provide programmatic access for automation scripts.

Developer Experience

The project ships with comprehensive documentation covering installation, configuration, and advanced usage. The source code is cleanly organized into app, templates, and static directories, making it approachable for contributors. The community is active on GitHub, with issues and pull requests reflecting a focus on stability and feature parity. Licensing under MIT removes any barriers to commercial use, making Otter Wiki an attractive choice for internal tooling or open‑source projects.

Use Cases

• Internal Knowledge Base: Small teams can spin up a wiki that is version‑controlled, auditable, and easy to back up via Git.
• Documentation for Open‑Source Projects: The Git HTTP server allows contributors to edit docs directly from their local repo, merging changes through standard Git workflows.
• DevOps Playbooks: By leveraging the API hooks, playbooks can be automatically regenerated or deployed when wiki pages change.
• Educational Platforms: Instructors can provide a collaborative Markdown space that students can clone, edit locally, and push back, integrating seamlessly with Git‑based grading systems.

Advantages Over Alternatives

• Git‑Native: Unlike many wikis that use relational databases, Otter Wiki stores content in Git, giving developers immediate access to diffs, branching, and distributed workflows.
• Lightweight & Fast: Flask’s minimal footprint keeps resource usage low, ideal for containerized microservices.
• Extensible UI: CodeMirror and Halfmoon provide a pleasant editing experience without the bloat of heavy WYSIWYG editors.
• Open Source & MIT: No licensing costs, full control over source code, and the ability to modify or extend as needed.
• Built‑in HTTP Git Server: Eliminates the need for a separate Git hosting solution, simplifying