BookStack is an open source, web-based documentation system, that allows you to create a structured knowledge store for personal, team, or company use. BookStack focuses on ease-of-use and design to provide an experience suitable for an audience with, potentially, mixed skills in technology. It's built upon the PHP framework Laravel, with MySQL or MariaDB used as a datastore.
I built BookStack after attempting to find a documentation or wiki system for my workplace. Confluence was the closest option to suit my requirements but the user-based pricing introduced a barrier. The closed nature of Confluence also raised questions to the longevity of the documentation I'd be building. In the end, I decided to build my own platform to suit my needs. I released it under the MIT license to give back to the open source community that I'd come to love and benefit from over the years.
Content hierarchy and organization options
To keep things familiar and intuitive, BookStack makes use of real-world book terms to describe its organization structure. Documentation content is created as a "Page":
- Pages belong to a specific "Book".
- Within a Book, Pages can optionally be grouped up into "Chapters".
- As your documentation grows, you can then use "Shelves" to categorize Books, with Books being able to be part of multiple shelves if needed.
This structure sits at the heart of BookStack, and can often be the love-it-or-hate-it deciding aspect of whether BookStack is suitable for your use case.
Upon this core hierarchy, BookStack also provides tagging, user favorites, and advanced search capabilities to ensure content remains discoverable.
Writing documentation
The primary method of writing documentation in BookStack is through the use of its what-you-see-is-what-you-get (WYSIWYG) editor, which makes use of the open source Tiny project. This editor provides a range of content formats including:
- Various header levels
- Code blocks
- Collapsible blocks
- Tables
- Images
- Links
- iFrame embeds
- Alert callouts
- Bullet, numbered and tasks lists
- Drawings (through intregration with the open source diagrams.net)
If you prefer Markdown, you can use the built-in Markdown editor, which provides a live preview and supports the same feature set as the WYSIWYG editor. If permission allows, you can even jump between these editor options depending on the page you're editing.
How your data is stored
Documentation is stored within a MySQL or MariaDB database in a relatively simple HTML format, in addition to the original Markdown content if Markdown was used. A lot of design and development decisions have been made to keep this HTML format simplistic. It uses plain standard HTML elements where possible, to ensure raw documentation content remains open and portable.
Uploaded images, attachments, and created drawings are saved on the local filesystem but can optionally be stored in an s3-compatible datastore like the open source MinIO.
To keep your content accessible, there are built-in options to export content as PDF, HTML, plain text, or Markdown. For external consumption, there's a HTTP REST API and a webhook system. In terms of extension, a "logical theme system" allows running of custom PHP code upon a wide range of system events.
Ready for business
BookStack comes with a range of features to support business environments. Support for a range of authentication options are built-in, including SAML2, OpenID Connect, and LDAP allowing easy single-sign-on usage with platforms such as KeyCloak. MFA options are available and can be mandated based upon role. An audit log provides full visibility of modification activities across an instance.
A full role-based permission system provides administrators full control over create, view, update, and delete actions of system content. This allows per-role system defaults, with options to set custom permissions on a per-hierarchy item basis.
A community of support
After being active for over 7 years, the community for BookStack has grown with various avenues for discussion and support. We now have:
- Our documentation site
- Video guides on YouTube
- A subreddit
- An active GitHub issues list
- Paid-for business support
If you want to play with BookStack, you can try it out on our demo site. To learn how to set up your own instance, visit the installation page of our documentation.
Comments are closed.