Gollum

Gollum is a lightweight, git‑centric wiki engine written in Ruby that turns any Git repository into a feature‑rich, web‑served knowledge base. At its core, Gollum treats the repository as a document store where each page is a plain‑text or markup file. The application watches the repo for changes, renders pages on demand using a plug‑in architecture, and provides an HTTP API for CRUD operations. Because the underlying data lives in Git, every edit is versioned, reversible, and can be distributed via standard git tooling. This makes Gollum an attractive choice for teams that already use Git for source control and want a lightweight wiki without a separate database.

Architecture & Technical Stack

• Language & Framework: Ruby 3.x, built on the Sinatra web framework for a minimal request stack. The core engine is a Ruby gem (gollum) that can be required in any Rack‑compatible application, allowing integration into existing Ruby on Rails or Sinatra sites.
• Rendering Engine: Uses the redcarpet Markdown parser, extended by custom extensions for Mermaid, PlantUML, KaTeX/MathJax, and CriticMarkup. Rendering is performed on the fly; a simple in‑memory cache can be enabled for production to reduce latency.
• Storage: The only persistent layer is Git. Gollum supports bare or non‑bare repositories, and can be pointed at any remote (GitHub, GitLab, Bitbucket) via SSH or HTTPS. All assets (images, PDFs, custom CSS/JS) live in the same repo.
• API Layer: Exposes a REST‑like JSON API for page retrieval, creation, update, and deletion. Webhooks can be configured to trigger external services on commit events, enabling CI/CD pipelines or notification hooks.
• Deployment: A single gollum executable can be run in development or production. For production, Gollum is typically served behind a reverse proxy (NGINX/Apache) or as a Docker container (gollumwiki/gollum). The Docker image pulls the latest gem, so CI/CD pipelines can spin up fresh instances quickly.

Core Capabilities & Extensibility

• Markup Flexibility: Supports multiple Markdown flavors (GitHub Flavored, CommonMark), Textile, reStructuredText, AsciiDoc, and custom markup via plugins. Developers can add new renderers by implementing the Gollum::Render interface and registering them.
• Advanced Features: Built‑in support for diagramming (Mermaid, PlantUML), bibliographic citations, inline math rendering, and page redirects. These are exposed as simple tags or directives in the markup, making them accessible to non‑technical users while still being programmable via the API.
• Plugin System: Gollum’s plugin architecture allows developers to hook into events such as before_page_render, after_commit, or on_page_change. Plugins can modify page content, enforce policies, or integrate with external services (e.g., Slack notifications).
• Custom CSS/JS: Users can drop custom stylesheets or scripts into the repo’s _assets directory, and Gollum will serve them with appropriate cache‑busting headers. This is useful for branding or adding client‑side enhancements without touching the server code.

Deployment & Infrastructure

• Self‑Hosting: Requires only Ruby, Git, and a web server. No external database or message broker is needed, simplifying the deployment footprint.
• Scalability: While Gollum is single‑process by default, it can be run behind a load balancer with multiple workers (e.g., Puma or Unicorn). Because all state is in Git, horizontal scaling is straightforward: workers share the same repo clone or use a shared filesystem (NFS) to keep the working directory in sync.
• Containerization: The official Docker image is lightweight (based on Alpine), making it ideal for Kubernetes or serverless platforms. Environment variables (GOLLUM_REPO, GOLLUM_BASEURL) allow dynamic configuration without code changes.
• CI/CD Integration: Developers can script commits to the wiki repository as part of release pipelines, generating changelogs or documentation automatically. Gollum’s API can be called from CI jobs to push updates, making it a natural fit for GitOps workflows.

Integration & Developer Experience

• Documentation: The project’s wiki provides exhaustive guides, API references, and plugin examples. Markdown files in the repo serve as living documentation, which is a boon for developers who prefer code‑first docs.
• Community & Support: Active maintainers and a growing contributor base mean that bugs are addressed quickly. The RubyGems ecosystem offers gems for authentication (OmniAuth), database integration, and monitoring.
• Configuration: Settings are controlled via a simple YAML file (config.yml) or command‑line flags. This minimalism reduces boilerplate and speeds up onboarding for new developers.

Use Cases

• Project Documentation: Teams can clone their GitHub/GitLab wiki locally, edit with VS Code or Vim, commit changes, and let Gollum serve the live site.
• Knowledge Bases: Small to medium enterprises can host an internal wiki without a separate CMS, leveraging Git’s audit trail for compliance.
• Educational Platforms: Instructors can version lecture notes and code snippets, using Gollum’s math and diagram support for rich content.
• DevOps Playbooks: Operators can store operational runbooks in a Git repo, with Gollum providing an instant web interface that automatically reflects the latest commit.