After moving my docs into my Dioxus app, the next question was pretty obvious.
What does a reusable docs setup for Dioxus actually need?
I did not want a giant CMS.
I did not want runtime content fetching.
I definitely did not want a fragile pile of custom glue code that works once and then becomes a weird private framework I regret later.
I wanted something boring, solid, and reusable.
That is basically how dioxus-docs-kit happened.
What the kit includes
Right now, the core pieces are:
- MDX content rendering
- sidebar navigation from
_nav.json - compile-time embedded content
- full-text search
- page navigation
- optional OpenAPI reference pages
- theme switching
Which is a fairly unsexy list, honestly.
That is a compliment.
These are exactly the boring pieces I kept wanting whenever I looked at docs setups for real app projects.
Why compile-time embedding matters
One of my favorite parts of the setup is that docs content is embedded at compile time.
The build helper reads _nav.json, finds the referenced .mdx files, and generates include_str!() calls for them.
So the result is simple:
- content ships with the app binary
- there is no separate content service
- there is no runtime file discovery mess
- deployment stays straightforward
For self-hosted apps, this is great.
The docs are just there. No second system pretending it is not a second system.
Navigation stays explicit
Navigation is driven by a _nav.json file.
I like that because it keeps the structure intentional.
I do not want a docs system making clever guesses about what my sidebar should look like based on whatever folder scanning logic happened to be easy to implement.
I would rather define the structure once and keep it explicit.
Boring wins again.
MDX without turning everything into a circus
I wanted Markdown-style authoring with enough room for richer content when needed.
That is where MDX helps.
Plain Markdown is great right up until it is not. Then suddenly you want richer callouts, custom components, or tighter control over how a page is rendered.
The goal here was not to make content authoring infinitely flexible.
The goal was to make it flexible enough without turning the docs pipeline into a cursed build experiment.
Search is not optional anymore
Docs without search feel fake surprisingly fast.
Once a project grows beyond a handful of pages, nobody wants to browse around politely. They want the answer.
So full-text search is built in.
That sounds obvious, but it is one of the first things that makes a docs system feel real instead of homemade.
OpenAPI pages are a big quality-of-life win
A lot of app docs eventually need API reference pages.
That is usually where people give up and bolt on yet another separate tool.
I did not want that.
So the kit supports optional OpenAPI integration.
Same shell. Same navigation. Same deployment. No weird handoff into a different docs universe.
Why this matters for real projects
This is not a crate for demo screenshots.
It is useful when a Dioxus product has real docs pressure.
A few obvious examples from my own stuff:
- SeggWat could use it for setup docs, widget docs, API references, and educational docs around feedback workflows
- infra.page could use it for integration setup guides, self-hosting docs, and example dashboard templates
- StepShots could use it for feature docs, workflow guides, and onboarding content that should be searchable instead of buried
That is the kind of product context I built it around.
Theme switching and app-native integration
Because this lives inside a Dioxus app, the docs can use the same broader UI approach as the rest of the product.
That sounds small until you live with a split setup for a while.
Theme switching feels more natural. Routing feels more natural. The whole thing stops feeling like a branded iframe with better typography.
One small but very real integration footgun
There is also one annoying practical detail the repo handles explicitly.
If dioxus-docs-kit is pulled from crates.io, Tailwind CSS 4 cannot scan ~/.cargo paths for class usage.
So the repo ships a safelist file you can copy into your project and reference from your Tailwind setup.
Not glamorous. Still the kind of thing that absolutely matters in a real integration.
The actual goal
The goal was never "let me build a docs framework because frameworks are fun."
The goal was simpler.
Make it easy to ship real docs with a Dioxus app, keep the content in the repo, and avoid turning documentation into another hosted system that slowly drifts away from the product.
That is the whole idea.
Top comments (0)