AmuseWiki

AmuseWiki is a self‑hosted, library‑oriented wiki engine that extends beyond simple page editing into a full authoring and publishing pipeline. Built on the venerable Emacs Muse markup, it preserves a large portion of Muse’s syntax while adding modern web‑centric features such as RSS feeds, mobile interfaces, and automated book building. The project is open source (MIT‑style license) and actively maintained on GitHub, with Debian/Ubuntu packages available for quick deployment. Its architecture is intentionally lightweight: a single Ruby process serves the site, with content stored as plain text files and metadata in YAML front‑matter. This file‑based approach keeps the codebase minimal, eases version control integration, and eliminates the need for a heavy database layer.

Technical Stack & Architecture

• Language: Ruby (≥ 3.0) – the core engine and web server are written in pure Ruby, leveraging standard libraries for file I/O, HTTP handling, and templating.
• Framework: A custom lightweight web framework built on rack and sinatra‑style routing, avoiding the overhead of Rails or Sinatra while still providing middleware support.
• Markup Parser: A fork of the original Emacs Muse parser, extended with Markdown‑style syntax extensions and a plugin hook system.
• Storage: Flat‑file content storage (Markdown/Emacs Muse files) with optional SQLite for user accounts and audit logs. This design keeps the deployment footprint small and allows developers to version content in Git or other VCS tools.
• Templates: ERB and Slim templates with a theming engine that supports custom CSS/JS bundles. Themes can be swapped at runtime without restarting the server.

Core Capabilities & APIs

• RESTful API: Exposes CRUD endpoints for pages, authors, and media. Authentication is token‑based (JWT), enabling integration with CI/CD pipelines or external CMS tools.
• Webhooks: Configurable webhook endpoints fire on page create/update/delete, allowing downstream services (e.g., search indexing or notification systems) to react in real time.
• Plugin System: Developers can write Ruby plugins that hook into the rendering pipeline, add new markup tags, or extend the admin UI. The plugin API is documented and includes lifecycle callbacks (before_render, after_save).
• Bookbuilder: A command‑line tool that compiles a subset of pages into EPUB, PDF, or HTML books using Pandoc. It supports custom templates and metadata injection.

Deployment & Infrastructure

AmuseWiki is designed for containerized environments. A minimal Docker image (alpine‑based) contains the Ruby runtime, dependencies, and a default configuration. The file‑storage model means that persistent volumes can be mounted to /data, making it trivial to scale horizontally: multiple instances behind a load balancer can serve the same content directory, with optional Redis for session caching. For larger deployments, a read‑replica setup can be achieved by syncing the content directory via rsync or Git hooks, while the API layer remains stateless.

Integration & Extensibility

• OAuth2 & LDAP: Optional authentication providers allow integration with corporate identity systems.
• Search: Built‑in full‑text search powered by Elasticsearch or Solr can be plugged in; alternatively, a lightweight SQLite FTS5 index is available out of the box.
• Custom Markup Extensions: Developers can define new block or inline elements in Muse syntax, enabling domain‑specific markup (e.g., mathematical formulas, code snippets with syntax highlighting).
• Third‑Party Themes: A theme registry lets developers publish reusable UI skins that can be installed via the admin panel.

Developer Experience

The project’s documentation is organized around a “Getting Started” guide, a comprehensive markup manual, and an API reference. Community support is active on Libera Chat (#amusewiki) and GitHub issues. The repository follows semantic versioning, with automated CI tests that run against Ruby 3.x and the latest Debian/Ubuntu images. For contributors, a clear contribution guide and code‑style linting make pull requests straightforward.

Use Cases

• Academic Publishing: Universities can host course notes, lecture transcripts, and research papers in a single system that supports both web browsing and e‑book export.
• Digital Libraries: Public libraries can ingest existing Muse files, enrich them with metadata, and expose a browsable catalog.
• Documentation Platforms: Open‑source projects can maintain internal documentation and public wikis with a lightweight stack that scales on modest hardware.

Advantages Over Alternatives

• Simplicity: No database migration or ORM required; content lives in plain files, easing backup and version control.
• Performance: A single Ruby process with minimal dependencies delivers low memory usage (<200 MB) and fast start‑up times.
• Extensibility: The plugin API and webhook system allow developers to tailor the engine without forking.
• Licensing: MIT‑style license permits commercial use and modification, unlike some proprietary wiki engines.

In summary, AmuseWiki offers developers a lightweight, extensible, and fully self‑hosted wiki solution that bridges the gap between traditional Emacs Muse workflows and modern web publishing, making it an attractive choice for libraries, academic institutions, and documentation teams that value control, performance, and open‑source freedom.