I've been working on BookStack for over 6 years now, learning a lot about open source project maintainership during that time. Originally developed it while looking for a documentation system for my mixed-technical-skill workplace. Wanted something easy to use without having to get finance involved when increasing our user count.
With Confluence backing away from their self-hosted offerings, hopefully many will find BookStack useful. It's not supposed to be a direct replacement, and the design & content structure is quite opinionated, but it can serve many of the same use-cases as Confluence had served.
Thank you, thank you, thank you. I use started using bookstack when I realized that I wanted a place for long form / long term storage of documents separates from my Notes / To dos. I love it and I deeply appreciate your hard work.
For others that haven't tried it, here's what clicked for me:
- An opinionated hierarchy of Book -> Chapter (Optional) -> Page
- Great search
- WYSIWYG OR Markdown supported
- Great integration into Diagrams.net
Thank you! I love to hear about the specific features people enjoy.
> WYSIWYG OR Markdown
I will state that switching between them is pretty flaky at the moment, is done at instance level and can cause HTML in markdown. Is designed to be choose-once-and-leave. That said, in rebuilding the editor I am aiming for easy and instant Markdown & WYSIWYG switching within editor.
Just on a practical level, you might as well just disable the option to convert, especially if you're going to swap it out anyway. Sometimes just flipping the switch on a task opens up a little cognitive space for the rest of your work. :)
Definitely not off topic. I do not use Obsidian but while Obsidian is a knowledge base software, I can absoslutely see the appeal of being able to organize your thoughts and notes into a full-fledged article and then push to something like Bookstack for public/team consumption.
Bookstack looks like an amazing feat of engineering — it’s overwhelmingly the wiki I want to deploy given other F/OSS options. just today I was showing it to a friend and it is impressive how clean and considered it is. Thanks for maintaining and improving this project
Impressive that you've stuck to it for more than six years. I remember testing an early version. Looks like you've made a lot of improvements in that time.
Thanks! I've learnt a lot in that six years. I've been quite proud of our constant, yet steady, pace of development while retaining upgrade compatibility (where possible).
Happy to help! I will say that I would in no way present it as an example of a clean codebase. 6 years of weekend and night development, while having significant code understanding/learning during that time, has lead to somewhat of a mix of ideas and approaches. Constantly trying to re-align things though!
Funny to stumble on this thread just days after we started evaluating BookStack for internal use! Thanks for this piece of software. I'm really enjoying it so far and am looking forward to integrating it into our daily processes.
That's cool. I recently built MFA into the access flow, with a sight to extend methods where needed, although any instance using the SAML/LDAP/OIDC auth options could enforce MFA on the identity provider side.
Glad to see any alternatives to confluence (or Atlassian in general). I've used Confluence for a good 4 years or so and for the life of me, I can not fathom why anyone would use this for storing documentation for code etc, as opposed to storing things direct in a repo. I can understand it's use somewhat for business folks, but even then, the way of organising things is abysmal, every solution (such as rich text editing) feels very off the shelf/MVP, uninspiring UI, the list goes on. It feels like most companies that use it already use the Atlassian stack of JIRA/Bitbucket, then feel the need to tack Confluence onto the end because it's there.
> I can not fathom why anyone would use this for storing documentation for code etc, as opposed to storing things direct in a repo.
Because storing documentation in repos doesn't work great when you want to organize your documentation, discover or search it.
Having thousands of documentation files in a repo, next to the code is unmanageable, much more than thousands of documentation files in Confluence. In Confluence, you can put rights, tags, titles, organize in folders, assign owners, put comments, ....
Is Confluence good at it ? Not much, but it doesn't mean we should remove Confluence.
Confluence is a fantastic way to ensure that nobody ever finds your documentation. The WYSIWYG editor is so painfully slow, buggy, and laggy, it actually reduces the chance of anybody bothering to update documentation. When organizations change names, URLs change completely and you can sometimes never find a linked page again after it moves. Navigation in confluence is painfully slow, even though it's a bunch of static text. Embedding code snippets or images is an exercise in frustration.
Confluence sucks! But it does have one of the best editing experiences I've seen (it also sucks, but less than the rest). You can privately draft pages before publishing them, get diffs of versions, it auto-saves and you even get real time collaboration with others. That's worth a lot, imo.
Interesting. Personally I feel that markdown is a far better editing experience, but that's mostly just a bias towards simple tools. If the confluence editor didn't huff, puff, lag, and choke on even simple documents, I might be able to bear it. But when it takes sometimes multiple seconds for a keystroke to register in the editor, I get so infuriated I just don't bother.
Agree about no one finding your documents. I have trouble finding my own documents in it, don't expect others to be able to find them. Unless you are absolutely obsessive about organisation and linking documents things remain a disjointed mess, would have been cleaner to store markdown in the file system in a directory tree than in confluence.
I mean, I know. I've wrote an article called "We deserve better than Notion and Confluence" and I spend my days building an alternative to Confluence for orgz.
But I still think that Confluence is better than nothing
Also an Atlassian here. For anyone wondering, we tend to use Confluence for planning, decisions, team process, tech specs, etc but use an internal view of DAC[0] for code docs. Think Hugo[1] crossed with redoc[2] with a dash of GraphQL support.
Unfortunately the docs-in-repo + PRs-for-updates approach has way more friction for drive-by-corrections/commentary/Q&A from people not on the team, so it's not a holy grail either.
There are a couple reasons I prefer docs in Confluence to docs in repo:
- I can update the docs without going through Git peer-review (admittedly this is a culture issue, not a technical one).
- We have "code-tangential" docs already in Confluence and it's nice to have one place to search
- Non-devs (like lawyers) find Confluence more familiar
I've taken to putting a link to the Confluence docs in the README so folks who find the code first can easily find the docs.
> I've taken to putting a link to the Confluence docs
Middle ground I've found on some projects: very detailed code/data-oriented notes are in markdown in the repo, tied to a PR. Those doc files may reference external items like confluence pages or specific tracking ticket/URLs that relate to the code at hand.
I was on a team that had everything in confluence, and everything was impossible to find. The closest I came to understanding it was the confluence docs were always initial plans, but were rarely updated. When updated, you wouldn't necessarily know if you needed to look through 5 versions to see earlier thinking, or which links to 'updates' confluence pages you needed to trawl through. It was as much a problem of a growing set of contributors and growing departments than anything else, but there was a new 'direction' every 6-9 months (when new folks would come in) and "this worked at my old company" so they'd document stuff however they wanted.
No one on the dev team bothered to ever look there for anything, because it was simply pointless. Few people ever looked at it for anything more than "recent updates" to see what's changed in the last 2-3 weeks. Discoverability on the size of that project (and this is 'only' 5 years old ~80 people) was just useless.
A handful of folks did keep 'onboarding' stuff relatively up to date, but it was less than a year old at that point. I suspect that if those folks moved on, those docs may slowly rot.
On the whole, keep written docs both updated and useful and findable to a growing number of people with disparate needs and different contexts and backgrounds... it's a lot harder than it might seem when first considering it. Even if you have the people on a team with the aptitude for it, it's usually low priority in every work cycle, and the first casualty when trying to hit deadlines.
In my old (and soon current again) shop we used confluence extensively, to get the best from both worlds we usually kept the documentation next to the code in markdown or asciidoc files and synchronized them to confluence in a CI/CD pipeline (confluence was read only for these sections) maybe I can open source these helpers when I'm back... a two way merge was also in the making :). we could sync whole file trees with automatic link crosslink generation, asset management and versioning support in confluence
I face the same problem as our company is heavily using the atlassian products (Jira/Confluence…)
I once found a plug-in that did almost the same, allowed Confluence to read and render markdown files directly from (private) GitHub repos thus allowing me to get the best of both worlds!
- docs stays in the repo (thus is much more likely to actually get updated)
- docs get exposed in Confluence (thus is accessible for the business folks that does not do git)
- docs are easy to update (as you can use any editor: vi, emacs, IDE’s etc)
So conceptually the same as you’re solution ;-)
Unfortunately we did not implement the plug-in as we have too many eggs in the Jira basket (+1.000 users) which have the unfortunate side effect that the licensing price is derived from the +1000 users even though only the much lower number of devs would use it.
That is one repeated problem we face in the Atlassian stack (well a source of their income…)- even a seemingly cheap plugin (extension or whatever they’re called) ends up in the person suggesting how to ‘work smart/not hard’ having to find the funding typically a two digit thousands of € or year (thus I never bother with that anymore :(
In my opinion this is the way to go, documentation close to the code but still indexed in a real knowledge management tool. That's one thing that we are building at Dokkument, but I would be really interested to know more about what you have done, especially how those files are then indexed on Confluence
I always found the ability to draft confluence docs then create jira tickets from within confluence to be the 'obvious' use case, but I don't often see people do it. Or... I've seen some orgs do it a lot, and some not at all (even when they have both jira and confluence together).
Size of org/team is probably a factor, but the linking between the two products is one of the few things I see it has that most other tools don't. It's probably because most other tools are single-use, and they focus on one or the other, but not both sides.
I think Confluence “shines” as a sort of “Wikipedia for your company” with the added benefit that it’s simple enough that anyone can create a nice looking page and there are plugins to cater to different disciplines.
And yes, it’s super bland and uninspiring. Just like Excel or Word. I consider it a feature.
> It feels like most companies that use it already use the Atlassian stack of JIRA/Bitbucket, then feel the need to tack Confluence onto the end because it's there.
Literally the only reason it exists. JIRA is the hook that gets companies on to the rest of the horrible Atlassian stack.
As if jira itself is not horrible. But to be fair to jira I recently tried the cloud version which is untouched by any scrum masters or management and its way better than what I have to endure in my day job with hundreds of customizations it has received over the years to shoehorn every kind of metric
I remember considering BookStack while looking for a (surprise) replacement for Confluence.
The main thing that led me to stop considering it pretty quickly is precisely the concept of books - I find it both unnecessarily complicated and unnecessarily limiting.
My Org now uses DokuWiki. It has a lot of issues (the prosemirror visual editor is a good start, but in beta and out of development, for example). But it's also the least sucking option I've found. Most Wiki software severely screws up the editing experience, which may not be such a good idea when you want to get people to document things. I'm glad Bookstack does this right.
As a former DokuWiki user (both pro and privately) the biggest issue is when you want to migrate from DokuWiki.
I managed to migrate my private docs from DokuWiki to markdown but it wasn't easy and it took some manual editing. I'm much happier knowing that it's in Markdown format simply because of the options that opens up for me.
Can anyone with experience with multiple wiki platforms compare this with XWiki and/or MediaWiki.
I may be asked to update $WORK's wiki, which is currently MoinMoin (IIRC), and am looking for anyone with more experience so I don't have to start testing from scratch. I've run MediaWiki before, but am not beholden to using it just because of past/current familiarity.
Importing from MoinMoin would be nice, but not absolutely required. LDAP integration (at least for authentication/LDAP binds) is mandatory, but LDAP group integration (authorization/permissions/roles) isn't mandatory: that can be internal to the app. Wouldn't mind it though: either Unix-style or AD-style (memberOf).
Mediawiki is page focused, needing a lot of tweaking to make it act like something other than a completely open public page editor. Trying to collect pages is annoying ugly; about the best you can do is with "categories." Mediawiki tries to do too much with document metatags and whatnot. Mediawiki is ugly/outdated looking (IMHO) and requires lots of php config file editing.
Bookstack has a lot more inherent document organization stuff (ie: books>chapters>pages etc), it's easy as hell to administer, and it looks gorgeous out of the box.
> Trying to collect pages is annoying ugly; about the best you can do is with "categories."
With vanilla mediawiki, sure. If you use Cargo or SMW, you can do pretty much anything you want, especially with Cargo. Add in Lua (Scribunto extension) and you have effectively a full extra layer in your stack.
(There's also DPL (Dynamic Page List extension) as an option; if what you're doing is easy enough to express, and you're just trying to build lists of pages, you may be able to get away with just doing DPL queries and nothing else beyond that.)
It might be more technically complex than you want it to be, but it's definitely not limited to categories.
I enjoy Cargo and DPL, they're powerful and great tools for automatically aggregating and filtering content, and I used both of them a lot at a MW that I was an admin on for several years. But it still isn't easy to build an ordered, hierarchical, book-like structure with book-like output, which was a constant request. It wasn't just technically complex (no users wanted to learn how to do it, they wanted one person to do it for them), it also didn't do the one thing most people wanted it to do.
The Collection extension did that, though, but Wikimedia's weird behavior around it and their multiple failed attempts at choosing a tech stack for output — OCG/ZIM, PoD/PediaPress, Electron (not that one)/Proton — much less the next step of building that functionality into a usable feature in MW, turned me off from trying.
I need to dig into BookStack (I imagine like most wiki flavors, it'll lack the templating features in MW that I rely on), but the fact that it's built on the book/chapter paradigm from the ground up instantly catches my eye.
Future XWiki employee (should start in March!). Feel free to reach out to XWiki [1] [2], they'll be happy to answer your question and address your specific needs. They are nice. Feel free to contact me if you'd prefer but I'll be less competent than them for obvious reasons.
I don't know many things about XWiki yet, but the main difference between MediaWiki and XWiki is probably the X in XWiki (eXtensible). XWiki is more like a development platform to build a website, a blog, or a collaborative platform (internal or public) that you can tailor to your needs. What you put as contents is highly customizable / scriptable and several Wiki syntaxes are supported. The XWiki syntax can be extended to support your custom features if needed. There are a lot of apps [3] to extend XWiki (some are paid, but open source anyway so you can compile them yourself). LDAP is supported. XWiki will also provide support or specific developments if needed.
MediaWiki is developed for Wikipedia first. That's what you can read on XWiki's website anyway. But if you don't need anything that MediaWiki doesn't already provide and like its UX, it can't be a wrong decision to go for it. Many people outside Wikimedia use it and the UX is familiar to everybody, and that's huge. Both tools can be self hosted (and MediaWiki is quite easy to install), MediaWiki is mostly in PHP, XWiki is in Java. XWiki can be hosted for you by XWiki SAS. They'll also help handle migrations from Confluence and are currently handling a lot of them, and I'm sure they will be interested by hearing about migrations from other tools too.
I guess WikiMatrix would be a good starting point [4]. XWiki also have comparisons to common collaborative platforms on their websites including MediaWiki. They are obviously biased, but don't lie neither. You might want to check them out.
I hadn't encountered Bookstack, before. The UI seems quite clean. I hope we'll have the pleasure to meet and discuss at some point! The UK is not far, we are neighbors. Hmm, neighbours!
edit: by the way, you might be interested by XWiki's online presentation at FOSDEM on the 5th of February [5], as well as any other presentation in the collaboration and content management devroom, because not everything collaboration is a wiki :-) [6]
There is a "semantic" extension to MediaWiki that makes it easier to support many enterprise use cases with data visualizations, custom queries (potentially referencing information from multiple wiki pages) and the like. It is somewhat widely used for wikis other than Wikipedia, that can simply defer to the Wikidata project for those needs.
SMW works okay but if you have technical ability, I'd recommend Cargo (https://www.mediawiki.org/wiki/Extension:Cargo) instead. It's a somewhat limited SQL wrapper (limited - e.g. subqueries aren't supported, which can be annoying on occasion but tbh I've only missed them maybe 3 or 4 times, wiki queries tend not to be too complicated) which is roughly equivalent to SMW in maybe 50% of use cases I've encountered, inferior in maybe 2%, and significantly better in the rest.
It definitely has a bit of a higher learning curve than SMW, especially for non-developers, and even for developers there's some kinda weird stuff going on with it (e.g. they have this HOLDS syntax sugar and list-type fields as an answer to SMW's ability to express one-to-many relations a bit more naturally than sql can; also there's this cargo_attach parser function that I forget to do 80% of the time and that's why my tables don't rebuild properly).
Anyway if anyone does use MediaWiki and is choosing between these extensions I'm happy to talk to you about them, this is what I do for my job & I have several years experience with both (though my SMW experience is somewhat outdated, since I switched to Cargo several years ago, and only recently have started using SMW again, and that only tangentially).
I'm currently helping set up a wiki for students of a STEM faculty, and we've settled on MoinMoin (v2, that is). We're broadly building on a previous MediaWiki setup, which we've found to be too "Wikipedia-oriented".
I've looked at a few very extensible and featureful wikis (XWiki, Tiki Wiki, TWiki, Foswiki), but for our usecase, they seemed overwhelmingly big (I know, I'm not easy to please). They're all almost application development/scripting platforms, which isn't necessarily a bad thing, but it would mean we'd have to learn a lot more if we wanted to modify parts of them. Of the four mentioned, XWiki looked like the most "polished", its conceptual model and code looked maintainable and it has a great number of actively developed plugins. If I'm not mistaken it even allows writing pages in Markdown, which was one of our criteria.
I also looked into taking a very lightweight wiki (LOC in the high thousands) and adapting it to our needs, but found that most of those didn't have a code model that would lend itself well to doing things like swapping out a custom format for Markdown, we'd basically be rewriting half the wiki at that point. Even DokuWiki, a relatively large project, is too blasé about running regexes on page contents for my taste.
We looked into BookStack, but didn't think its content model would work too well for our idea of a wiki as a "social" site. Maybe it's just the terminology, though.
In the end, we ended up running MoinMoin 2. It's in a perpetual beta state, but it is actively maintained. The main reason was its code quality: It's small enough that understanding how it all fits together is quick, and it's structured so that adding functionality or swapping out one part of it is easy (as much as it could be for software that's over a decade old, anyway). We're programmers anyway, so we decided to go with the ability to change the wiki to our liking over initial polish. So far, I've made a new theme, wrote a script for migrating from MediaWiki, changed out the Markdown parser and added SSO with CAS. The changes aren't public yet, but will be soon.
So far I'm happy with our decision, but note that my search was heavily subjective, you very likely have other requirements and preferences.
EDIT: By the way, the criteria were loosely:
- Modifiability (I wanted a custom theme, needed a non-traditional SSO option and could see us
getting ambitious about custom functionality)
- Hierarchy + ideally tags for organising
- Ability to export some pages into a print version (annually published leaflet/book for new students)
- Permission system (which we hopefully won't need to use)
- Storing pages in Markdown (helps with converting for print too)
- Macros (I'm a fan, easy-to-write extensions would be just fine)
> I also looked into taking a very lightweight wiki (LOC in the high thousands) and adapting it to our needs, but found that most of those didn't have a code model that would lend itself well to doing things like swapping out a custom format for Markdown, we'd basically be rewriting half the wiki at that point. Even DokuWiki, a relatively large project, is too blasé about running regexes on page contents for my taste.
Just fyi, MediaWiki does have support for using a different page content mark up languages (Content models in mediawiki speak). In the default that's mostly only used for special purposes like CSS pages (See Special:ChangeContentModel), but the interfaces are relatively clean if you want to add your own.
I looked into a million wiki/documentation projects and my absolute favorite for consumption (reading and navigation) was Docusaurus [1].
The only problem is that Docusaurus is intended for static public documentation, so it does not provide user-accounts or multi-topic content-management that you would expect from bigger wiki-like projects.
I wish Docusaurus would expand its scope to serve as a wiki, rather than single-purpose documentation - but I understand these are different use-cases altogether.
From a quick look at the demo it looks nice, however i think that since people are more likely to read than edit, the "Actions" should be lower than the navigation panels. E.g. in this:
Instead of "Actions", "Page Navigation", "Book Navigation" it should be "Page Navigation", "Book Navigation", "Actions".
Note: this seems to be an issue when the window width isn't too high to put the actions at the right side. I only noticed it after i wrote the above since i use a narrow width for the browser as my monitor is large and it makes it easier to read text. Regardless, in this "narrow mode" i think the actions should be placed after navigation.
I used to use Dokuwiki as my personal notes app/knowledgebase pretty heavily. Switched to Bookstack two years ago and never looked back. It has everything you need in a Wiki, no third party plugins needed like Dokuwiki.
The API is excellent, and I've used it to build some custom stuff. They recently added webhooks too.
And Dan is pretty responsive on Discord if you need help.
There are still a few things I'd like to fix before really feeling confident in publishing it to the index, but I guess I might as well because it does already provide some value.
Really enjoy your project! Setting it up on a free Oracle cloud VPS is very straightforward, setting up automated backups is also very easy and restoring is again, very very easy! Thank you for your hard work on this project, it made me start working on my own take on how notes should be handled and it gave me a place to keep things that I find interesting and keep notes on everything I learned throughout uni over the past couple of years.
Thanks! Interesting to hear about the backups and restore being easy, I often hear complaints due to not having in-app backup/restore but the risk of causing issues, over doing that at an infrastructure level (Via mysqldump/file-copies), has always been a point of worry for me when thinking down the in-app route.
Thanks for creating and maintaining BookStack. My company has used it for around three years, and recently integrated it with Okta for SSO. It’s fast, simple to use, and the recent search improvements have really made it an excellent product.
Awesome to hear. Especially happy to hear good feedback regarding the search improvements, I spent a good amount of time on those and this is the first feedback I've had since.
Out of interest, does your company support the author via sponsorship or other means?
I’m curious… I wondered what the red tape is like in organisations that use open source projects like this in order to setup a GitHub sponsorship or similar.
In a previous role at a cash-strapped startup I used open source software within my team and have to admit I never arranged any contributions to the OSS projects - though if I had my time again in that role I’d be more mindful about trying to do this. Especially I think when the project is a very small or “one person” team.
Great comment and very interesting to read your perspective on it.
Really if we’re honest, any company using Bookstack should be able to afford to chuck you $20/month or something (barring perhaps one-person bootstrapped startups). It’s likely red tape, bureaucracy and the internal culture that prevents this more than financial means.
And especially so if support demands are being made of you!
Yeah. The reason we’re running a lot of our own open source stacks is that getting anything officially approved has to go through multiple layers of bureaucracy and approvals.
Getting approval to throw an open source project some money is likely to be even crazier (probably not a concept they ever imagined).
Some time ago I was trying to transition to platform to help me capture my own personal notes and organise my knowledge. BookStack was a good front runner, but I think the lack of mobile editing along with the hassle of upgrades made me end up using Notion.
Now by all means notion isn't perfect at all, but for me who just wanted to start writing notes it seems the right choice at the time.
I would like to switch to BookStack as it looks great and is a great product, but the one issue that worries me is when it comes to upgrades and migrations. Generally I found when upgrading database based platforms I end up messing up hugely causing myself a huge headache, and then eventually not upgrading at all. For example I used Monica CRM, and totally botched the upgrades eventually just closing it down and using Google contacts instead.
If there was an easy way to solve for that I'd definitely be on board with self-hosting it myself. But at the moment I just don't have the time to resolve upgrade issues :(
I can understand that, Especially since Monica and BookStack share the same framework. Database issues do happen unfortunately, although I take changes pretty seriously when approach schema changes. For those that have requested support upon such issues, I've been able to get them up and running again in the vast majority of cases.
Should also check out MediaWiki. The last year the visual editor is finally included with PHP, making the installation simple:
https://mediawiki.org/wiki/MediaWiki
A visual editor does not solve mediawiki's bloat which is useless for 99% of anyone who isn't Wikipedia or another large organization, nor MediaWiki being entirely organized around pages. Nor does it solve Mediawiki's ugly, Web 1.0 design.
In Bookstack, making the server private is one or two clicks. In mediawiki you have to set at least half a dozen config file variables.
Adding any of a slew of auth methods is trivial in Bookstack. In mediawiki it's finding an extension, figuring out how to configure it, and then worrying about keeping it up to date.
Bookstack is focused on "books", chapters, pages, sections - not "pages."
It's perfect for what most people and projects need, and it looks fucking gorgeous out of the box to boot.
> It's perfect for what most people and projects need, and it looks fucking gorgeous out of the box to boot.
Thank you so much!
> In mediawiki it's finding an extension, figuring out how to configure it, and then worrying about keeping it up to date.
I've always attempted to be "batteries included" with BookStack due to this frustration. Means we have to be more limited in abilities but hopefully provide a better experience for what we do allow.
> In Bookstack, making the server private is one or two clicks. In mediawiki you have to set at least half a dozen config file variables.
This isn't really true. During install process you are asked which you want. If you press the private button when prompted you get a private wiki. If you press public you get public.
If you want to change after you installed, you do have to edit a text based config file. You only have to edit two lines, but i appreciate that text based config file is a turn off for some people.
> Bookstack is focused on "books", chapters, pages, sections - not "pages."
I agree that this is a significant difference from mediawiki. You can do that sort of thing in MediaWiki, but you'll be swimming upstream.
No not really any point in also checking out MediaWiki. Bookstack has surpassed MediaWiki in usability by leaps and bounds. They are not even comparable any more, aside from being able to do wiki edits they are separate use cases by now.
This looks like a great piece of software. I was never a fan of Confluence, but that is more that Confluence, I feel is backwards. Since confluence, the few opinions is has, is reverse. You typically get some kind of set up like Confluence Space is owned by a person, who then adds approved editors. The default should be open editing, then locking down to specific people. What typically seems to happen in confluence shops is that information ends up being organized by TEAMS not by topic. Which is a terrible way to document. This idea of Books -> Pages seems to be more opinionated that would hopefully get people to not make this mistake.
Used confluence in several shops and never seen anything like that happen. Sounds terrible. Spaces are usually few and edit for all. Must have been bad admins and management.
Doesn’t mean it’s a good product though. Especially the cloud version is progressively worse, especially with regards to performance. Glad to see some competition in the area.
> What typically seems to happen in confluence shops is that information ends up being organized by TEAMS not by topic
It is usually a better idea to organize information by teams than topics in an organization. The reason is that if the tree structure is unknown to most people, they will not be able to find information easily nor to choose the right place to create information.
You shouldn't expect everyone to browse the whole documentation to understand how it is structured in order to be able to use it
Personally I managed to run Outline using a standard OIDC software like Keycloak. While more troublesome it should work just fine without external tools
Yeah, this has been requested a few times. I don't come from a hosting background (Outside of managing my own VPSs) so I don't feel it's something I can personally do (at a level of service I'd be happy with) but the idea of partnering with someone that has experience is something I've though about; The tricky part is finding someone I can trust enough to send users to.
For sure. Honestly, I would love to have an established open-source respecting company like RedHat come along and say "We'll be your official hosting partner, we'll handle hosting, payments and offer these services, we'll need x hours from you per week for support, otherwise focus on the project, we'll give you £x per month, You retain ownership and other revenue streams."
A bit idealist and of course the contract would be more complicated, but to focus on the project while having established support would be ideal.
I think this isn't a good strategy for the project, at a commercial level. They currently have a well define niche. Competing in a much larger market without a clear competitive advantage won't work.
Confluence + Jira is a common combination. It is good to have an alternative to one of these. Anyone has info or suggestion on what are good open source alternatives for Jira?
Jira is a monster that does way too much but that's probably why everyone uses it - execs hear of all the features it has without thinking about how the end users feel about it. The Jira replacement will depend a lot on the reasons you use Jira and what features you need.
More focused on writing explicit long-form content organized into book-like trees (i.e. book -> chapter -> page), instead of doing things TheWikiWay. It's much nicer for technical documentation IMHO.
It looks nicer than most wiki software out of the box, has nice integrations and editor stuff. So aesthetically it's very pleasing and it's pretty easy to use (the big asterisk is when performance gets in the way and suddenly stuff is slow).
In theory I'm sure you could sit around, write a billion plugins to some other wiki software, and get to confluence. But you could also just pay for Confluence!
"As nice as Confluence but super speedy" is a ... $50 million dollar business (can't say billion cuz I mean atlassian does good work!)
Had a look around, this looks really polished. I would have one remark - please consider making tables a first-class feature.
In my experience with Confluence, the easiest and most comprehensive way to organize information is with tables. Having a quick way to merge, delete, color cells would be great. Right now, coloring and merging are hidden away in some menus, and deleting cells will shift the bottom toolbar with the table upwards, so you can't do it quickly.
Yeah, Tables are a challenge in general. The trouble with them from an editor perspective is the range of desired options and control (Many each at table, row, cell level) is fairly vast.
I'm currently in the process of building a new content editor which I'm hoping would provide better opportunities to make such controls more intuitive.
It doesn't need to be Word or Excel-levels of options and control, less is actually more - for example table cells in Confluence can only have 6 colors, and no fancy border styles etc. which in my opinion provides a more unified look and feel. Just the UX needs to flow smoothly enough, as working with tabular data consists of doing many of the same steps over and over again.
I've been planning on rolling this out at work for months now, just finished setting up a little server for the office to host it on. Its going to help so much.
I looked into Bookstack three years ago when searching a replacement with a better WYSIWYG editor for my DokuWiki instance so my wife could participate in the Wiki.
I can't exactly remember, why I did not chose Bookstack, but I was positively impressed with the demo. Nice to see its continuously evolving.
Similar to you, after some fun trying it out I landed on wik.js. Curious why you did too.
For me wiki.js had more capability for importing previously exported pages from OneNote and a more flexible document structure. In the end we went back to confluence though, as wiki.js lacked the capability to change the effective directory path of multiple pages (had to be done one at a time or via the API).
I really like both bookstack and wiki.js and they occupy a very similar niche. Do check them both out.
My ultimate wiki platform wishlist: comments module, markdown and attachment import/export, extremely fast tree hierarchy editor and renaming, and a good editor that enforces a fully standardized markup. Looks are nice too.
Wow. What a coincidence. I installed this last night on my NAS. Came to HN to check if this product has been discussed before and there is a discussion from just today!
Anyway, I was wondering if there is a plug-in infrastructure for BookStack in on the roadmap?
Thank you for the product. Looks neat in the minimum time I have spent on this so far.
There's no particular "plugin" system. I've always aimed for BookStack to be a "batteries included" system with the essentials built-in and supported with the core.
That said, I have been opening up areas for extension, especially over the last year or two. The following systems are now available:
- REST API [1]
- Webhooks [2]
- Visual Theme System [3] (Overrides of any view/translations/icon used).
- Logical Theme System [4] (Back-end logical hooks/events/extension).
It's possible we could build a common container around these methods to form a "plugin" system but that would require significant time & thought. Not sure I'll ever soon go down that route though due to the cost it could burden upon the project. My current stance is providing opportunities for extension to those who'll be able to maintain it themselves.
I came across your software a few weeks ago when I was looking for some kind of locally hosted collaborative documentation suite for internal use, basically, a wiki that can be used by people who aren’t programmers. I was a bit incredulous when I found that it is basically expected to use markdown if you want to have a wiki. This really raises the barrier to entry and restricts users to ones that are technically proficient and have the time to learn and deal with markdown. Wysiwyg is a necessity.
Easy content insertion is also necessary. We haven’t yet integrated bookstack, but I don’t see any alternatives (sticking with the locally hosted requirement)
Not sure if this fully fits your needs but you might want to look at Wiki.js. You can self host it, has WYSIWYG editor available (as well as HTML and markdown). I'm not associated, just use it for some time.
Yeah, wiki.js is in the same space and seems to be pretty great. BookStack and wiki.js have taken quite different design & structure choices though so I usually advise trying out the demos of both to see what best fits.
The only issue I have with many Confluence alternatives is that they don't support multiple people editing the same document, at the same time, à la google docs. Does this? I can't tell from the landing page.
Does not support this at the moment. Currently rebuilding the editor with a vision to potentially support that in the future although there'd be some hurdles to jump over to get to that point.
It is extremely offputting that Saga doesn't show a single actual product view, the site design makes me think the product is equally ugly, and they require signing up to see a demo?
When a company hides the product that much and forces you to only experience it with a tour guide, it's tacit admission the product sucks.
I agree that it's frustrating when a company hides their product, but I think the saga website design is really nice and they do have an actual video of the platform front and center (Instead of one of those fake simplified "representations" that may companies use).
I just ran into this problem with Notion earlier this week. It was really disappointing how bad the experience was with even just two people trying to work on the same document. I quickly gave up.
Atlassian did not consider small businesses with regulatory requirements when it decided to push everyone to the cloud. Atlassian's cloud cannot ever meet my regulatory requirements, by 2024 I need to replace Confluence. There is no way I can pay for the cost of the Data Center version of Confluence you'll be able to self-host, over $20K/year to self-host Confluence is a non-starter.
Does BookStack index uploaded files for search? If so, what formats does it support?
Can pages (or books) be exported in common formats?
> Does BookStack index uploaded files for search? If so, what formats does it support?
No, unfortunately not. You can attach files but we only support indexing (And parsing) of core page content. Indexing other formats opens up a large branch of maintenance while adding potential confusion in the platform in regards to what's considered content.
> Can pages (or books) be exported in common formats?
Yeah, Both can be exported as plaintext, markdown, contained-html or PDF. The PDF export can be troublesome but works for most simple use-cases.
Just trying it out and the simplicity and user friendliness is great. Thank you for such a nice piece of software, we'll give it a try and use it in our company.
Is there a way or do you plan to add page translations? Some of our contributors do not speak English and I wonder what is the best approach to have pages translated, apart from creating a copy of a page and keeping all copies in sync.
Another option I've been considering for a change away from Confluence is Gitbook. Curious to hear if anyone has done an in-depth comparison of these two.
This can really depend on your use-case and audience.
Things like gitbook (& docusaurus) can often be better for focused topics or when serving product documentation to users.
BookStack tends to work better as a mixed-topic, mixed-user platform. Along the lines of an internal wiki shared by different teams. I've seen people attempt to use BookStack as a replacement for GitBook but struggle due to the structure being different.
I like that it's OSS, and obviously many will like the option to self-host, however some like to also have the choice of it being hosted (mainly for ease of management/security) - this usually also offers a revenue stream for the project.
Quickly looking at it, seems like it would work out better than Confluence, which we've been using, but found it (Confluence) to be slow to fix/implement features.
No hosting offerings from myself right now although there are a couple of companies offering hosting (One of which is a sponsor on the homepage linked in the post).
What about extensibility? A very important reason why people use Confluence and Jira is there's an infinite supply of add-ons to do almost anything you may want to do, and then you can even implement your own.
Nothing user-friendly like confluence but some core systems are available to customize and extend. Of course, since BookStack is open source, some people have taken the option of maintaining a fork with deeper customizations.
One of the benefits of Counfluence is that it is one of the only Wikis where I've seen non-technical people being able to create content on a daily basis. Linking pages, inserting graphs and images just works. I have yet to see that in anything based on markdown.
Yeah, non-technical folk were one of my key audiences for BookStack which most other popular open-source offerings, at the time, seemed to lack focus for. People do love their markdown input though.
I'm currently rebuilding the editor; My goal is it have an easy WYSIWYG editor that allows instance back-and-forth switching to Markdown. One of the tricker parts is avoiding obscure/custom markdown syntax for non-common/custom content blocks, as one of my main principals is to ensure user content is portable/non-proprietary.
I'd say that simplicity can very much depend on audience, use-case and opinion. The design and content structure between platforms appears quite different.
BookStack does support Markdown content editing although it is WYSIWYG or Markdown, jumping between the two isn't really supported (Yet, Hoping to achieve this later this year).
I haven't used Confluence or BookStack in this case. Does these platforms have git like version controlling and collaboration in them? What about login and admin stuff? Also gitbased blog platform like architecture perhaps?
I am a big fan of journaling, documentation and having a knowledge hub. I am not sure what is out there for a monolithic yet shared and controllable knowledge hub.
There's is good versionimg in confluence, and also good search. The editor is also nice (improved a lot since a few years ago). Compared to the mess that is JIRA, I actually like confluence.
This is something that has been requested before, although not something I'd probably look to include in the core project since I attempt to avoid custom formats and syntax where possible. That said, I'd like to get to a point where something like mermaid.js can easily be added if desired. Over the last year the BookStack platform extensibility has grow significantly (API, Webhooks, PHP Hooks, View/Language/Icon Overries) and I'm looking to continue that to achieve such requests without over-stressing the core project itself.
Whoa I can copy/paste images directly into the editor, sweet!
One question though, if I deploy a containerized version via docker and upload images, where do the images reside (it seems like the php uploads folder? Just curious if I had to redeploy the image what volumes I might have to mount as back-upp
It depends on the container you use, Most seem to provide guidance on what paths you'll need to mount as volumes. I know the linuxserver.io [1] container puts all required files into a single `/config` directory to mount.
I'm not sure how Confluence permissions work. Within BookStack pages (Main content) is generally within a hierarchy of Shelves > Books > Chapters > Pages. Both shelves and chapters are optional parts of the hierarchy,and Books can be members of multiple shelves.
General permissions (Edit/Create/Delete) can be controlled per-role, and multiple roles can be assigned to a user. Permissions can then be overridden per hierarchy item. Permissions for Books and Chapters will cascade to child items unless they're overridden.
I'll trial it out tomorrow. I can see on individual pages (books?) you're tracking changes, e.g. created and last edited. Are these changes tracked in a history page for version control by any chance, ssdanbrown/OP?
> Are these changes tracked in a history page for version control by any chance, ssdanbrown/OP?
Most system changes (Create, Updated, Delete actions) are recorded and displayed in an audit log view for admins. As of the most recentl release, you can trigger webhooks upon any of these; Video example [1].
Changes to pages (where documentation content exists) do have their state changes recorded so you can revert/view/compare across versions of a page. The revision limit is set to 50 by default (I think) but this is configurable.
You can login to the demo as an admin to preview these features if needed [2].
We actually moved from Confluence to Bookstack last year, mainly because the EOL for the Atlassian server-licenses. Sure, it has less features, but the main function, maintaining content by non-tech people works great!
Impressive. I'm definitely going to give this a look. Right now, we've got our technical docs in Sharepoint (yeah, that Sharepoint), mixing its built-in docs and Word docs, and I'd really like to get rid of that.
Thanks! My original scenario was a mix of gist code snippets and word docs. The horror is when those word docs are version by file name (server_docs_final-v2.docx). It definitely helps to get things aligned into a platform that people understand how to use.
This looks great! One thing which would be useful would be an approver role or step for document creation and updating. In a lot of orgs it's necessary to have someone sign off on changes to sop's
I've been looking for something just like this. Does it support migration from Confluence? I glanced over the features section and didn't see mention of that, but perhaps I missed it?
Unfortunately no readily available migration path from Confluence. I'm not familiar enough with Confluence myself to understand the formats and options that we'd need to carry across & support.
Our API [1] has recently matured to now support the different content types so that could be utilised for such a migration job although the API is still growing to cover more actions/models.
Have recently been thinking about possibly offering some form of paid service support service to help the process and help fund the project.
Oh, prepare for some fun with ADF (atlassian document format) if you ever do try to build migration from confluence. On the positive side you’ll have to deal with only one flavor, but I swear they have like 10 different ways to present/format their documents across all their products.
Fortunately, a lot of the handling is open sourced in atlaskit.
one of the things we use confluence for is tagging people to tasks. putting pages underneath pages and when things are checked off they show up on the parent page so employees have all tasks and then the meeting tasks, then plus all the wiki features but the above was what sold us on confluence for doing meetings and minutes. I haven't been able to find something similar.
If you're happy with wikijs I'd advise that you probably stay on it to be honest. WikiJS is a great project. They two differ quite a bit in design and structure, if wikijs's structure works well for you already you may find yourself fighting against the BookStack structure/layout. Can always give the demo [1] a go to get an idea.
If it only had backup within the interface, would that cover most of your wish?
Reason being, I always have troubling thinking about backup AND restore, but mostly because restore is a complicated mess (Especially when you start thinking about going across versions). Just achieving backup within the interface (Of database and uploaded files) is much more feasible.
That's a tricky one to answer! The authentication systems most likely, just because of the different standards and configuration that different people demand. I've had to learn LDAP, SAML2 and OIDC protocols to a level that allows me to confidently add & maintain these systems.
> non technical
Probably issue handling & management, from a mental point of view. Dealing with such a range of ideas and requests with an ever-growing list of features/issues/support-request has been tricky. I've had to learn to change my perspective and goals when dealing with GitHub issues.
In general the social side has been a massive point of learning and challenge to me. I've recently written about many of these more extensively here:
Sorry this is nothing like Confluence. On Bookstack you click a link and get a new page instantly. This is nothing like Confluence where you need to wait 5-8 seconds for each page.
And no, I will never not shit in Atlassian products until they fix performance. Trello is the standout. Thanks for not trashing it.
I hear this a lot from people switching from Confluence. I watched a colleague using Confluence once and was surprised how much time was spent looking at those text-placeholder blocks while content was presumably loading in the background.
My favorite is when elements jump around while they load, so you're guaranteed to misclick on links. So then you'll have to wait again (when going back), because of course the cache hasn't been invented yet.
Maybe BookStack can do fine for a company with a few dozens of employees. But Confluence can handle tens of thousands of employees. So I wouldn't label Bookstack as a Confluence alternative.
Maybe I'm missing something, but BookStack doesn't even have a notion of "teams" only roles. You can't give permission of a file to a user, only to all users who have a certain role.
But I'm certainly biased as I'm building a real Confluence alternative
> Maybe BookStack can do fine for a company with a few dozens of employees. But Confluence can handle tens of thousands of employees. So I wouldn't label Bookstack as a Confluence alternative.
Sure, but there are a lot of people within that range up to tens of thousands. I have had some people mention using BookStack within environments towards to tens of thousands (Although it's likely a lesser portion enganged). Just because it may not achieve that one factor does not discount it as an alternative for significant audience.
> Maybe I'm missing something, but BookStack doesn't even have a notion of "teams" only roles. You can't give permission of a file to a user, only to all users who have a certain role.
Yeah, we don't have the word usage of "Teams" but I'm not sure what that'd offer in addition to roles. Role specific permissions can be applied to any of the hierarchy elements (Including upon page content).
I'm certainly not criticizing BookStack. It actually looks super responsive and have a great set of features to manage knowledge especially for an open source platform.
As for roles. In organizations of a certain size, the concept of role is not organization wide, but team-wide. You will set for example the editor role, for some people of the team "Operations". Don't really see how this can be done on BookStack
Confluence is terrible in all kinds of other ways. To be frank, it's the worst company documentation software I've ever used. Discoverability is terrible and it's easy to end up in a situation with thousands of pages that quickly fall out of maintenance because features for organization are an after thought. Its own markup is terrible and its Markdown import support similarly so.
Most wikis are terrible at evergreen notes: the only one I can think of that might be moving the ball forward is Athens Research though I wasn't able to get their self-hosted beta running and I host dozens of other services with Compose.
Obsidian might be good too, but they don't seem too keen on supporting large business collab usecases even though enterprise is a cashcow.
> Confluence is terrible in all kinds of other ways.
I disagree, Confluence is used by tens of thousands of organizations and they don't have a very good Sales strategy, that means a lot of business choose them when they could have choose something else. So I can't buy that it is terrible everywhere.
Can we do better ? Hell yeah. But I agree with you that most of Confluence competitors are in the SMB space even though money is in large enterprise. (But that's why we are building Dokkument)
That's not wikis that are bad at evergreen notes, that's evergreen notes that are not suitable for sharing with teams. Athens or Roam research, or others works well for one person, but can't work for teams.
> Confluence is used by tens of thousands of organizations and they don't have a very good Sales strategy, that means a lot of business choose them when they could have choose something else. So I can't buy that it is terrible everywhere.
I don't believe the number of users in an enterprise segment buying into a software is at all indicative of the usefulness of a piece of software. Atlassian products are typically sold between people who will not be the primary users of that software.
I have yet to see a SWE missing or desiring an Atlassian product. GitHub and other SaaS products yes but never Atlassian.
I also disagree that evergreen notes aren't suitable for teams. Notes that receive a lot of attention, or are high touch, are by definition evergreen. We need more of these in orgs but most of us don't know how to tend to our companies digital gardens. A huge part of it is wordly digital cruft akin to technical debt that accrues. As it grows in size it compounds the problem of discoverability.
Note-taking is a skill that receives precious little attention, despite being so critical to knowledge work AKA anything SWEs work with daily.
At the end of the day, people need to be able to discover notes if you want these to be useful. Just talking about evergreen notes without offering a way to discover those notes by anyone is useless.
Here's where we agree! I'd love better discoverability built in to these products. It'd be a huge boon, personally, at my workplace (that uses Confluence :-().
That's where Roam Research has a point. Creating a graph is appealing, as it is easier to browse and so discover things. That's also how Wikipedia works. But Wikipedia would never have worked without Google.
In organizations the best thing to do imo is to have everyone follow the same rules. Even bad rules that everyone follow is better than everyone following its own rules. And that's clearly one thing that Confluence sucks at. But the rules can't either be the same for anyone anywhere, so there is some balance to find. The other area that can help discoverability is curation
I would be happy to have a chat with you, don't hesitate to reach out to paul at dokkument com
With Confluence backing away from their self-hosted offerings, hopefully many will find BookStack useful. It's not supposed to be a direct replacement, and the design & content structure is quite opinionated, but it can serve many of the same use-cases as Confluence had served.