Show HN: We built a FOSS documentation CMS with a pretty GUI(kalmia.difuse.io)
kalmia.difuse.io
Show HN: We built a FOSS documentation CMS with a pretty GUI
https://kalmia.difuse.io/doc/
37 comments
Congrats on launching! Quick question: is this closer to WikiJS (https://js.wiki/), TinaCMS (https://tina.io/), Docusaurus (https://docusaurus.io/), or something else?
Thank you so much! Great question. Kalmia actually borrows elements from all three, but in different ways:
* On the GUI side, it leans heavily towards TinaCMS. We even considered using TinaCMS directly (Tinasaurus (https://github.com/tinacms/tinasaurus)) but ultimately built our own for better integration with our backend.
* For the backend (MDX -> HTML) generation, it's very similar to Docusaurus. We use a tool called RsPress, which is part of the RsBuild/RsPack tool suite. It's relatively new, but because it's written in Rust, it's much faster than Docusaurus. (Fun fact, if you look at the commit history you will see that we initially used Docusaurus but then migrated away from it!)
* Wiki.js is extremely extensive, but it’s dropping support for SQLite, which was a big factor for us. Also, its frontend for documentation doesn’t feel as fast as RsPress (you can try ours out on kalmia.difuse.io it's hosted on single core azure server). The biggest reason we didn’t go with Wiki.js was the versioning system—it felt clunky (or non existent for entire docs?). In Kalmia, versioning the entire documentation is just a one-click process.
So, in short, Kalmia combines a TinaCMS-like editing experience with Docusaurus-like static site generation, but with speed advantages from the latest Rust based tooling for SSG.
* On the GUI side, it leans heavily towards TinaCMS. We even considered using TinaCMS directly (Tinasaurus (https://github.com/tinacms/tinasaurus)) but ultimately built our own for better integration with our backend.
* For the backend (MDX -> HTML) generation, it's very similar to Docusaurus. We use a tool called RsPress, which is part of the RsBuild/RsPack tool suite. It's relatively new, but because it's written in Rust, it's much faster than Docusaurus. (Fun fact, if you look at the commit history you will see that we initially used Docusaurus but then migrated away from it!)
* Wiki.js is extremely extensive, but it’s dropping support for SQLite, which was a big factor for us. Also, its frontend for documentation doesn’t feel as fast as RsPress (you can try ours out on kalmia.difuse.io it's hosted on single core azure server). The biggest reason we didn’t go with Wiki.js was the versioning system—it felt clunky (or non existent for entire docs?). In Kalmia, versioning the entire documentation is just a one-click process.
So, in short, Kalmia combines a TinaCMS-like editing experience with Docusaurus-like static site generation, but with speed advantages from the latest Rust based tooling for SSG.
It looks closer to https://www.getoutline.com/
I actually just discovered Outline yesterday! It's an awesome platform. Our feature set isn't as extensive (yet), especially when it comes to integrations—they've really nailed that. However, many of the other features, like live collaboration and better security, are things we're actively working on and should be available in the next few releases.
One major difference between Outline and Kalmia is the license. I believe Outline uses BSL, while Kalmia is AGPL.
One major difference between Outline and Kalmia is the license. I believe Outline uses BSL, while Kalmia is AGPL.
We self-hosted Outline like two weeks ago in our company (15 people) and the acceptance is overwhelming positive. We tried different tools in the past: WikiJS, XWiki, docuwiki, Bookstack and there was quite a big resistance in using it. Main reasons where like, missing core functions e.g. no live collaboration, no e-mail notifications on commenting, no diagram functions, strange rules regarding page organisation, etc.
Outline feels mentally really lightweight but checks all boxes that we searched for. Some people says its quite similar to Notion, but without the automatisation stuff (I have no experience with Notion).
Slab is another one (we use it, but have no connection to it) https://slab.com/
Would be happy to switch to a self-hosted FOSS alternative though.
Would be happy to switch to a self-hosted FOSS alternative though.
Good question that led to insightful responses. I would like to bring GitBook (https://gitbook.com) too to the comparison notes (no affiliation).
They, too, focus on the collaborative, 'similar-to-git-workflow', and versioned approach towards documentation.
Happy to see variety in the 'docs' tools area, and really appreciate it being FOSS. Looking forward to trying out Kalmia on some project soon.
They, too, focus on the collaborative, 'similar-to-git-workflow', and versioned approach towards documentation.
Happy to see variety in the 'docs' tools area, and really appreciate it being FOSS. Looking forward to trying out Kalmia on some project soon.
I browsed the documentaton a bit and struggle to understand. CMS for me means "web server side application that stores data". However I don't understand how this goes together with "Cross-Platform Compatibility: Run Kalmia virtually anywhere thanks to its Go-based architecture."
I couldn't find a roadmap for the project but I would suggest to implement some sort of SSO. At work it was so much easier to justify bringing in a new tool like https://www.getoutline.com/ where we could use OIDC to integrate with Gitlab user management.
I couldn't find a roadmap for the project but I would suggest to implement some sort of SSO. At work it was so much easier to justify bringing in a new tool like https://www.getoutline.com/ where we could use OIDC to integrate with Gitlab user management.
Thank you for the feedback! I understand the confusion. Kalmia is indeed a server-side CMS, but its Go-based architecture allows it to be lightweight and run on various platforms, from cloud servers to smaller setups like Raspberry Pi.
Think of Kalmia as similar to Docusaurus, but with a built-in GUI—one of the most requested features from the Docusaurus community (https://docusaurus.io/feature-requests/p/make-content-editin...). With Kalmia, non-technical users can contribute to documentation without needing to know Git or Markdown, making content editing much easier.
We store the documentation data in a database (Postgres or SQLite), and markdown/HTML is generated only when updates, deletions, or creations happen. The built HTML is stored in memory for fast access, ensuring performance remains smooth even for large docs.
We’re also working on features like export to zip and GitHub Pages support, so users can host their docs externally if needed.
Regarding SSO, it’s a great suggestion. We’re looking into integrating Single Sign-On (SSO) to streamline user management and improve security. This will help with easier adoption in environments that already use OIDC for authentication. (We already supported OAuth with Github/Microsoft/Google)
Thanks again for your thoughtful input, and I appreciate you checking out Kalmia!
Think of Kalmia as similar to Docusaurus, but with a built-in GUI—one of the most requested features from the Docusaurus community (https://docusaurus.io/feature-requests/p/make-content-editin...). With Kalmia, non-technical users can contribute to documentation without needing to know Git or Markdown, making content editing much easier.
We store the documentation data in a database (Postgres or SQLite), and markdown/HTML is generated only when updates, deletions, or creations happen. The built HTML is stored in memory for fast access, ensuring performance remains smooth even for large docs.
We’re also working on features like export to zip and GitHub Pages support, so users can host their docs externally if needed.
Regarding SSO, it’s a great suggestion. We’re looking into integrating Single Sign-On (SSO) to streamline user management and improve security. This will help with easier adoption in environments that already use OIDC for authentication. (We already supported OAuth with Github/Microsoft/Google)
Thanks again for your thoughtful input, and I appreciate you checking out Kalmia!
Using Rust for markdown parsing seems like the epitome of driving a racecar to the grocery store- I’m curious if you have any metrics as to how much build time was reduced with that over using something like Node. I’d guess it’s <10ms.
We saw nearly the same reduction in build times (~80-90%) as quoted in the official RsPress documentation. Keep in mind, we're using MDX, not just plain Markdown.
Source: https://rspress.dev/guide/start/introduction#build-performan...
Source: https://rspress.dev/guide/start/introduction#build-performan...
There can be more of a difference than you might expect. In static site generators, Eleventy is about as fast as you can get in the JavaScript world, and is still 2-3x the time for Hugo in Go [1]. A couple orders of magnitude more than <10ms in this test which is predominantly markdown parsing.
Anecdotally, for large or extra large sites, the build performance gap between even Eleventy and Hugo can be quite large. And the gap from either of those to the newer JavaScript tools like Next.js is enormous.
1: https://www.11ty.dev/docs/performance/#build-performance
Anecdotally, for large or extra large sites, the build performance gap between even Eleventy and Hugo can be quite large. And the gap from either of those to the newer JavaScript tools like Next.js is enormous.
1: https://www.11ty.dev/docs/performance/#build-performance
I have yet go understand how people built slick UI like this.
Is this Chakra UI? The notification that shows up and bounces a bit, I've seen that on other websites too.
Is this Chakra UI? The notification that shows up and bounces a bit, I've seen that on other websites too.
CSS animations. Here's a drop-in one https://animista.net/play/entrances/bounce-in/bounce-in-righ...
Tailwind! And tailwind based component libraries like flowbite made of all these possible.
It might be Mantine UI: https://ui.mantine.dev/
[deleted]
Nice framework! I think it's missing a graph view that shows the connections between documents. Something like what Quartz provides. https://quartz.jzhao.xyz/
is the website dog-fed? first thing I looked for and couldn't find (hence left) was a demo instance
Pretty sure that the site itself (the documentation that is linked to) is built with it.
This is accurate, we also use it for one of our other products here https://docs.difuse.io/, although a demo instance for people to play around with is not a bad idea, will look into that.
I'd like a CMS for static files so non git users can edit my hugo/whatever static sites (marketing, docs, etc).
Are there any that just work with markdown and git repos?
Are there any that just work with markdown and git repos?
I don’t think there’s an existing tool that handles Markdown and Git repos without requiring users to interact with Git directly.
We’re currently developing a feature that allows you to push directly to Git from Kalmia. Instead of pushing Markdown, we’ll push the compiled HTML/JS output, eliminating the need for a build step in the Git repo and making CI/CD processes unnecessary.
We’re currently developing a feature that allows you to push directly to Git from Kalmia. Instead of pushing Markdown, we’ll push the compiled HTML/JS output, eliminating the need for a build step in the Git repo and making CI/CD processes unnecessary.
One of the saas hosting companies made one for Hugo iirc, but it looks like crap and is pretty basic.
It's a pretty easily solvable problem but I guess developers are focussing on bigger markets.
I'd want to keep the build step since I may pull markdown from other sources like I think astra allows.
I really just want to be able to give access to a marketing team to update the blog etc as a nice UI over using markdown and git (which is never going to happen).
It's a pretty easily solvable problem but I guess developers are focussing on bigger markets.
I'd want to keep the build step since I may pull markdown from other sources like I think astra allows.
I really just want to be able to give access to a marketing team to update the blog etc as a nice UI over using markdown and git (which is never going to happen).
> I'd want to keep the build step since I may pull markdown from other sources like I think astra allows.
Pushing without building is not a difficult thing to do, in-fact it will make changes much faster too. But you mention pulling markdown files from other places, merge conflicts are bound to happen that way right? And AFAICS there would not be an easy way to manage that automagically without human intervention.
Pushing without building is not a difficult thing to do, in-fact it will make changes much faster too. But you mention pulling markdown files from other places, merge conflicts are bound to happen that way right? And AFAICS there would not be an easy way to manage that automagically without human intervention.
No I think it'd be enough to have them separate to avoid merge conflicts.
It could probably be done in a separate step or something so users can edit files once they've been pulled in from other sources, at which point the repo becomes the source of truth.
It could probably be done in a separate step or something so users can edit files once they've been pulled in from other sources, at which point the repo becomes the source of truth.
Looks great! Why do you need a database? Seems like that limits the deployment options. You can't deploy to github pages, for example.
Good point! We use a database (SQLite or Postgres) to enable more advanced features like versioning, collaboration, and access control, which aren't easily managed with static files alone. The database also allows us to scale better for teams with frequent updates.
While it does limit deployment to platforms like GitHub Pages, Kalmia is designed for teams that need more than just static documentation—think of it as a middle ground between static site generators and fully dynamic CMS solutions. For purely static sites, there are other great options out there, but Kalmia focuses on more interactive, collaborative documentation.
That said, we’re actually interested in providing an option for users to export and deploy it to platforms like GitHub Pages or similar, so stay tuned for future updates on that!
While it does limit deployment to platforms like GitHub Pages, Kalmia is designed for teams that need more than just static documentation—think of it as a middle ground between static site generators and fully dynamic CMS solutions. For purely static sites, there are other great options out there, but Kalmia focuses on more interactive, collaborative documentation.
That said, we’re actually interested in providing an option for users to export and deploy it to platforms like GitHub Pages or similar, so stay tuned for future updates on that!
You could look into frontmatter to store metadata within the files, and just load it all into memory on startup. Even for huge projects, that probably won’t hurt anyway.
We already load all the documentation assets into memory whenever something changes. Even with large projects spanning hundreds of pages and page groups, it remains very fast—under 1 second in our testing.
That being said, there are some cases where a database is necessary. For example, handling multiple people editing the same document simultaneously wouldn’t work well with just flat files. Also, where would we store user emails/passwords for authentication? Another feature Kalmia supports is private documentation, where users need to log in to access certain docs (there's a simple toggle to enable authentication).
That said, adding an "export to zip" or "push to git" button is totally feasible, and it's something we've had a lot of requests for. While we don't personally use it, we'll be adding it so people can host their docs on static file platforms without needing Kalmia as the backend.
That being said, there are some cases where a database is necessary. For example, handling multiple people editing the same document simultaneously wouldn’t work well with just flat files. Also, where would we store user emails/passwords for authentication? Another feature Kalmia supports is private documentation, where users need to log in to access certain docs (there's a simple toggle to enable authentication).
That said, adding an "export to zip" or "push to git" button is totally feasible, and it's something we've had a lot of requests for. While we don't personally use it, we'll be adding it so people can host their docs on static file platforms without needing Kalmia as the backend.
The nice thing about flat files represented in memory would really be maximum performance, no external data store necessary, and easy portability. I definitely understand that sorting out concurrency by using a DBMS is easier, however.
> Also, where would we store user emails/passwords for authentication?
For this kind of application, I’d strongly recommend (and request from anything I buy) OAuth signin via my existing identity provider. That means I don’t have yet another location for accounts, and you don’t have to worry about storing them securely.
> Also, where would we store user emails/passwords for authentication?
For this kind of application, I’d strongly recommend (and request from anything I buy) OAuth signin via my existing identity provider. That means I don’t have yet another location for accounts, and you don’t have to worry about storing them securely.
[deleted]
Should use LLMs to extract documentation from source code.
Recently, we decided to open source it, as we believe others might benefit from a lightweight, customizable documentation system like this. We're excited to see how the community can take it further, contribute, and adapt it to their own needs!