A lot of docs tools feel great right up until you want them to stop being "the docs tool" and start being part of your actual product.
That was the point where Mintlify started annoying me.
To be fair, Mintlify was not pulling my docs out of the repo. The content was still there. So this is not a "hosted docs bad" rant.
The real friction was simpler:
- the docs still felt like a separate hosted surface
- I wanted tighter integration with the app itself
- I wanted full control over routing, rendering, and layout
- I wanted better control over URLs, metadata, internal linking, and the broader SEO shape
- and yes, downtime on the hosted side is still downtime for your docs
Mintlify can be totally fine. It just stopped fitting what I wanted.
So I switched.
I now self-host my docs inside my Dioxus app, keep the docs in the repo, and use my own docs kit instead of outsourcing the whole thing.
TL;DR: If you are already building in Dioxus, self-hosting docs inside the app gives you simpler deployment, tighter ownership, and better control over the full docs plus SEO setup than a separate hosted docs surface.
Why I wanted docs inside the app
Mostly because I got tired of the split.
If the docs are part of the product, I want them to live like part of the product.
That means:
- same repo
- same deployment
- same routing model
- same design system
- same ownership
I did not want the docs to feel like a polished annex attached to the real app.
I wanted them to feel native.
For a solo builder, every extra moving part becomes maintenance tax eventually. You might not notice it on day one. You definitely notice it later.
What was wrong with the hosted-docs setup
The problem was not that Mintlify was bad at docs.
The problem was that I no longer wanted docs-as-a-service.
Hosted docs tools optimize for convenience first. That is fair. That is the whole pitch.
But once you care about deeper integration, the tradeoff changes.
I wanted:
- docs that feel like part of the app, not adjacent to it
- content stored right next to the code it documents
- a path to publish blog-style pages without bolting on another system
- full control over rendering and shipping
- tighter control over URLs, metadata, internal linking, and how docs pages support the rest of the site
At that point I was not really asking for a hosted docs product anymore. I was asking for docs that behave like application pages.
What I built instead
I built dioxus-docs-kit, a reusable docs framework for Dioxus 0.7.
It gives me:
- MDX-based docs pages
- sidebar navigation from
_nav.json - full-text search
- page navigation
- optional OpenAPI reference pages
- theme switching
- compile-time embedded content
That feature list is nice.
But the bigger win is that it lives inside the app.
The docs are not a separate product anymore. They are just part of the product.
That sounds obvious, but it changes a lot.
Real examples from my own projects
This only gets interesting when you think about real products, not toy repos.
That is why I keep looking at it through projects like:
- SeggWat, where docs, setup guides, widget install docs, and educational content should stay close to the product
- infra.page, where self-hosting docs, integration setup guides, public dashboard templates, and config references all want to live near the app
- StepShots, where onboarding docs, workflow guides, and search-friendly content are part of the product experience, not an afterthought
In all three cases, I would rather have docs live with the app than rent them as a separate surface.
Why this is better for a solo builder
1. One deployment
I deploy the app and the docs together.
No extra hosted docs service. No separate deployment flow just to update documentation. Fewer places for things to drift or break.
2. Docs stay closer to reality
When the docs live in the repo, right next to the code, it is harder to forget them.
Not impossible, sadly. But harder.
And harder is already a real improvement.
3. I own the UX
If I want the docs to match the app, they can.
If I want custom routing, layout tweaks, embedded product-specific components, or search behavior that fits the app, I can do that without fighting the boundaries of a hosted platform.
4. I get better SEO control
This part matters more than people admit.
I do not just want docs pages to exist. I want control over:
- URL structure
- page metadata
- canonical rules
- internal linking
- how docs connect to blog content
- how blog content connects back to product pages
That is much easier when the docs are part of the same system instead of a separate hosted surface with its own defaults.
The tradeoff
Obviously this is not the right choice for everyone.
If your goal is to ship decent docs this afternoon with almost no engineering effort, a hosted docs tool is still a pretty reasonable choice.
But if you are already building in Dioxus, and you want docs to feel native, self-hosting starts looking a lot better.
Especially if you are a solo builder and you care about long-term leverage more than short-term convenience.
Why I turned it into a reusable kit
At first this was just me scratching my own itch.
Then it became pretty obvious that other Dioxus apps would want the same thing.
So I pulled it into a reusable package instead of hiding the setup inside one project.
That is what dioxus-docs-kit is for.
A docs site framework for Dioxus apps that keeps content local, ships with the app, and still gives you the important docs features people expect.
What comes next
In the next post, I will break down what is actually inside dioxus-docs-kit, including MDX support, compile-time content embedding, search, OpenAPI pages, and theming.
Repo: https://github.com/hauju/dioxus-docs-kit
Crate: https://crates.io/crates/dioxus-docs-kit
Top comments (0)