The Documentation Challenge
Let’s be honest—managing documentation is a pain. It’s tedious, it’s boring, and for some reason, no one ever seems to do it right. At least, that’s how it felt at Difuse before we created Kalmia. We were tired of drowning in a sea of half-baked solutions that were either too complicated or too slow. We needed a system that was:
- Accessible to the whole team, from developers to non-techies who think a “pull request” is something you do with curtains.
- Easy to maintain without requiring you to learn Git wizardry or some arcane Markdown dialect.
- Fast—because no one has time to wait for their documentation changes to be “approved” by a slow CI/CD process.
Below given is the admin panel screenshot for Kalmia and the user facing frontend respectively, you can see the live demo here.
(For all your white mode/flashbang enjoyers, we have that too!)
1. Accessible to All Team Members
In every tech company, you’ve got a mix of people—some who speak in code and others who think “JavaScript” is just a fancy way of saying “website magic.” (Spoiler alert: JavaScript isn’t that magical, but more on that later.) So we set out to create a solution that:
- Non-Developers Can Actually Use: We’re talking about something so intuitive that even your marketing team can add to the docs without breaking a sweat (or the site).
- Developers Won’t Hate: You know, the ones who need to document complex systems but would rather debug a memory leak in C++ than deal with convoluted documentation tools.
The idea was simple: the best person to document a change is often the one who requested it—so let’s make it easy for them to do just that.
2. Simplified Maintenance
Look, we’re all for powerful features. But if your documentation tool requires a PhD in DevOps just to push an update, it’s not helping anyone. We found platforms like Docusaurus and RsPress great—if you’ve got the time and patience to deal with them. We wanted something different:
- No Git Knowledge Required: Seriously, who wants to teach half the team how to rebase?
- User-Friendly Editing: No more fiddling with Markdown, YAML, or any other three-letter acronym that makes your eyes glaze over.
- Collaborative Editing: Because sometimes, it takes a village to write two paragraphs about a feature no one’s going to use.
3. Instant Deployment
You know what’s worse than writing documentation? Waiting for it to go live. We didn’t want a system that required you to sacrifice an hour of your day to the CI/CD gods every time you updated a typo. Instead, we aimed for:
- Changes That Are Visible Immediately: No more waiting around for builds to finish—just save and go.
- Simple Version Control: Avoid the headaches of traditional version control. Just click on “Create New Version” and you’re good to go!
Enter Kalmia: Our Solution
So, we built Kalmia—a documentation system that just works™. It’s simple, fast, and designed to make everyone’s life easier, whether you’re creating the docs or just trying to find them.
How Does Kalmia Compare?
So, what’s the big deal? How does Kalmia stand out?
We’ve tried it all. For Difuse and our DMSBG-100, we started with mdBook—a great tool if you like speed but not so much if you want something that non-techies can use. Then we moved to Gitbook—fantastic versioning, but it wasn’t fast enough and was burning a hole in our pockets. (Hundreds of dollars a month? No thanks.)
Docusaurus and RsPress? Cool, but they brought us back to square one—too complex for the team and a pain to deploy.
That’s why we created Kalmia, the documentation system that doesn’t make you want to tear your hair out.
How Does Kalmia Work?
In a nutshell, Kalmia is built on a Go backend with a React + TypeScript frontend. (Yeah, we went with React. We’ll explain why in a minute.) It features a versatile markdown editor for real-time edits. The backend takes care of markdown files, stores them in a database, and serves them to the frontend with the speed of Usain Bolt. For markdown-to-HTML conversion, we use RsPress—a Rust-based tool that’s faster than anything we’ve found.
Kalmia supports SQLite or Postgres databases, and switching between them is as easy as flipping a light switch—thanks to GORM.
Why Kalmia is Different
Now, let’s talk tech:
Go is Awesome: We love Go. It’s fast, it’s simple, and it’s why we were able to ship Kalmia’s first v0.0.1 release in just over two months. Sure, we spent 70% of that time polishing the frontend, but Go made sure our backend was rock solid with minimal effort.
React + TypeScript: We know, we know—JavaScript frameworks are a dime a dozen. But React has the support and the libraries we needed, especially for our editor, which gave first-class support for React. Could we have used Svelte? Probably, and we’d have had a blast doing it because Svelte’s DX is unparalleled. But we chose React because it was the pragmatic choice at the time. Next project, though? Svelte, here we come!
RsPress: We started with Docusaurus, but each build took so long that we had time to rethink our life choices. Then we found RsPress, which is not as polished but blazingly fast. It was a no-brainer.
SQLite/Postgres: We love SQLite for embedded devices—it’s lightweight and just works. But for cloud services, we’re all about Postgres. So Kalmia works with both. Pick your poison.
License: We went with AGPLv3 because we believe in giving back to the community and didn’t want to deal with proprietary limitations. Kalmia is open-source, free, and will stay that way.
Conclusion
Want to learn more? Head over to https://kalmia.difuse.io to see Kalmia in action. Or, if you’re the hands-on type, check out our GitHub repository. We’ve got a detailed README with setup instructions, and we’re always looking for contributors and feedback.
So go ahead, give Kalmia a try—and let us know what you think. We built it because we were tired of documentation systems that just didn’t get the job done. We believe Kalmia changes the game.
Oh, and if you’re a JavaScript developer—no hard feelings. Just know that there’s a better way, and its name is Go.
