dioxus-docs-kit

Reusable documentation site kit for Dioxus applications.

Drop-in layout with sidebar navigation, full-text search, page navigation, OpenAPI API reference pages, mobile drawer, and theme toggle. Built on dioxus-mdx for content rendering.

Quick Start

Add to your Cargo.toml:

[dependencies]
dioxus-docs-kit = "0.2"

1. Build a Registry

The DocsRegistry holds all parsed content, the navigation tree, the search index, and any OpenAPI specs:

use dioxus_docs_kit::{DocsConfig, DocsRegistry};
use std::sync::LazyLock;

static DOCS: LazyLock<DocsRegistry> = LazyLock::new(|| {
    DocsConfig::new(
        include_str!("../docs/_nav.json"),
        doc_content_map(), // HashMap<&'static str, &'static str> generated by build.rs
    )
    .with_openapi("api-reference", include_str!("../docs/api-reference/spec.yaml"))
    .build()
});

2. Wire Into Your Router

Create a thin layout wrapper that provides the DocsContext and registry to the library components:

use dioxus::prelude::*;
use dioxus_docs_kit::{DocsContext, DocsLayout, DocsRegistry};

#[component]
fn MyDocsLayout() -> Element {
    let nav = use_navigator();
    let route = use_route::<Route>();

    let current_path = use_memo(move || {
        // extract the slug from your route
    });

    let docs_ctx = DocsContext {
        current_path: current_path.into(),
        base_path: "/docs".into(),
        navigate: Callback::new(move |path: String| {
            nav.push(/* build route from path */);
        }),
    };

    use_context_provider(|| &*DOCS as &'static DocsRegistry);
    use_context_provider(|| docs_ctx);

    rsx! { DocsLayout {} }
}

3. Add Routes

#[derive(Routable, Clone, PartialEq)]
enum Route {
    #[layout(MyDocsLayout)]
        #[route("/docs")]
        DocsIndex {},
        #[route("/docs/:..slug")]
        DocsPage { slug: Vec<String> },
}

That's it. The library handles sidebar rendering, search, page content, previous/next navigation, and mobile responsiveness.

Components

Navigation Config

Define your docs structure in _nav.json:

{
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "pages": [
            "getting-started/introduction",
            "getting-started/quickstart"
          ]
        }
      ]
    }
  ]
}

Content Pipeline

All doc content is embedded at compile time via include_str!(). A typical build.rs reads _nav.json, collects all referenced .mdx files, and generates a HashMap<&'static str, &'static str> mapping paths to content.

See the example project for a complete build.rs implementation.

Styling Setup

This crate requires Tailwind CSS 4, DaisyUI 5, and @tailwindcss/typography.

Install dependencies

bun add tailwindcss @tailwindcss/typography daisyui

Configure Tailwind

Add to your tailwind.css:

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "daisyui" {
    themes: dark --default, light;
}

@source "./src/**/*.{rs,html,css}";

Include dioxus-docs-kit classes

When using as a crates.io dependency, Tailwind can't scan the crate source (it lives in ~/.cargo with machine-specific paths). Copy safelist.html from the crate into your project root and add it as a source:

@source "./safelist.html";

The safelist includes all classes from both dioxus-docs-kit and dioxus-mdx, including dynamic runtime classes that Tailwind cannot detect from source scanning alone.

When using as a workspace path dependency, you can point directly at the source instead:

@source "./crates/dioxus-docs-kit/src/**/*.rs";
@source "./crates/dioxus-mdx/src/**/*.rs";

Features

• web (default) — enables web-specific features (propagated to dioxus-mdx)

License

MIT