BookStack vs Mercurial

What BookStack is

BookStack is an MIT-licensed, self-hosted documentation application built around shelves, books, optional chapters and pages. It provides role and content-level permissions, multiple enterprise authentication options and a permission-aware REST API, but the operator remains responsible for the PHP and database stack, upgrades, filesystem permissions, security configuration and complete database-plus-file backups.

What Mercurial is

Mercurial is GPL-licensed distributed source-control software in which each normal repository copy contains local project history for offline commits, branches and merges. The Python-based core can be extended with bundled or external extensions, but hosting, review workflows, identity, backups and CI are separate choices that must explicitly support Mercurial repositories.

What BookStack is built to do

Book hierarchy

Organizes page content within optional chapters, books and reusable bookshelves.

Roles and permissions

Combines system roles with content-level overrides and inherited controls.

Federated authentication

Documents OIDC, SAML 2.0 and LDAP configuration for self-hosted instances.

REST API

Provides token-authenticated JSON endpoints governed by the API user's permissions.

What Mercurial is built to do

Local repositories

Keeps project history locally for offline commit, diff, branch and merge operations.

Clone, pull and push

Exchanges changesets between independently administered repositories.

Named branches and bookmarks

Provides multiple mechanisms for organizing lines and heads of development.

Extensions

Adds or changes commands through bundled, third-party or custom Python modules.

Choose BookStack if

• Internal handbooks, runbooks and technical knowledge bases with a clear hierarchy
• Organizations needing self-hosting, role controls and supported identity integrations
• Teams that can automate upgrades, database and file backups, and restore drills

Skip BookStack if

• You need a vendor-operated SaaS with no infrastructure responsibility
• Your information model cannot fit shelves, books, chapters and pages
• You cannot preserve the database, uploads, configuration and original APP_KEY together

Choose Mercurial if

• Existing Mercurial codebases that need continued distributed version control
• Teams whose required host, CI and editor integrations explicitly support Mercurial
• Workflows that benefit from Mercurial's core command model and selected extensions

Skip Mercurial if

• A required hosting or delivery service supports only another version-control system
• Critical extensions are unmaintained or depend on unstable Mercurial internals
• You expect the core tool to include hosted reviews, identity management and backups

BookStack: pros & cons

• Predictable structure: Shelves, books, chapters and pages give teams a constrained documentation hierarchy.
• Granular access: Roles can be combined and overridden at shelf, book, chapter or page level.
• Authentication choices: Official administration docs cover OpenID Connect, SAML 2.0 and LDAP.
• Automation surface: The REST API covers content and administrative resources while enforcing the API user's roles and permissions.
• Self-hosting burden: PHP, MySQL or MariaDB, web-server configuration, updates and monitoring are operator responsibilities.
• Manual recovery design: There is no built-in full backup and restore; both database records and instance files must be protected.
• Key dependency: Restores need the original APP_KEY for encrypted features such as multi-factor credentials.
• Hierarchy trade-off: The book metaphor is approachable but may constrain teams needing free-form graphs or complex publishing workflows.

Mercurial: pros & cons

• Distributed operation: Developers can commit and inspect full local history without a central server connection.
• Consistent core interface: The project documents a compact command model with hazardous behavior moved behind opt-in extensions.
• Extension system: Bundled and external Python extensions can add commands or alter workflows.
• Active releases: The official project page lists maintained release notes through the current release line.
• Hosting not included: Access control, code review, issues and remote availability require hgweb or a compatible external service.
• Integration validation: Teams must confirm that chosen IDE, CI, deployment and hosting tools support Mercurial.
• Extension compatibility: Archived installation guidance warns that internal API changes can break extensions or dependent tools.
• Archived wiki risk: The former project wiki is explicitly marked discontinued and potentially outdated, so current docs take precedence.