Dioxus Docs Kit

Integration Guide

Add dioxus-docs-kit to your own Dioxus project step by step

Overview

This guide walks you through adding dioxus-docs-kit to an existing Dioxus 0.7 project. By the end, you'll have a fully functional documentation site with sidebar navigation, search, and optional OpenAPI reference pages.

Prerequisites

  • A working Dioxus 0.7 project with features = ["router", "fullstack"]
  • The Dioxus CLI (dx): curl -sSL http://dioxus.dev/install.sh | sh

Setup

1

Add dependencies

Add dioxus-docs-kit and the build helper to your Cargo.toml:

toml
[dependencies]
    dioxus-docs-kit = { path = "crates/dioxus-docs-kit" }

    [build-dependencies]
    dioxus-docs-kit-build = { path = "crates/dioxus-docs-kit-build" }
2

Create the docs directory

Create your content structure:

text
docs/
    ├── _nav.json
    ├── getting-started/
    │   └── introduction.mdx
    └── api-reference/
        └── overview.mdx

Each .mdx file needs frontmatter:

mdx
---
    title: Introduction
    description: Welcome to the docs
    sidebarTitle: Introduction
    icon: book-open
    ---

    Your content here.
3

Configure navigation

Create docs/_nav.json:

json
{
      "tabs": ["Docs", "API Reference"],
      "groups": [
        {
          "group": "Getting Started",
          "tab": "Docs",
          "pages": ["getting-started/introduction"]
        },
        {
          "group": "API Reference",
          "tab": "API Reference",
          "pages": ["api-reference/overview"]
        }
      ]
    }
4

Create build.rs

Add a build.rs at the project root to embed content at compile time:

rust
fn main() {
        dioxus_docs_kit_build::generate_content_map("docs/_nav.json");
    }

This reads _nav.json, emits cargo:rerun-if-changed for all MDX files, and generates a content map in OUT_DIR.

5

Wire up the registry

In main.rs, use the doc_content_map!() macro and create the DocsRegistry:

rust
use dioxus::prelude::*;
    use dioxus_docs_kit::{
        DocsConfig, DocsContext, DocsLayout, DocsPageContent,
        DocsRegistry, use_docs_providers,
    };
    use std::sync::LazyLock;

    // Generates doc_content_map() from the build script output
    dioxus_docs_kit::doc_content_map!();

    static DOCS: LazyLock<DocsRegistry> = LazyLock::new(|| {
        DocsConfig::new(
            include_str!("../docs/_nav.json"),
            doc_content_map(),
        )
        .with_default_path("getting-started/introduction")
        .build()
    });

To include an OpenAPI spec, chain .with_openapi():

rust
DocsConfig::new(nav_json, content_map)
        .with_openapi(
            "api-reference",
            include_str!("../docs/api-reference/openapi.yaml"),
        )
        .build()
6

Create the docs layout wrapper

Create a layout component that provides DocsContext and the registry. The use_docs_providers hook bundles all the context setup into a single call:

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

        let current_path = use_memo(move || match route.clone() {
            Route::DocsPage { slug } => slug.join("/"),
            _ => String::new(),
        });

        let docs_ctx = DocsContext {
            current_path: current_path.into(),
            base_path: "/docs".into(),
            navigate: Callback::new(move |path: String| {
                let slug: Vec<String> =
                    path.split('/').map(String::from).collect();
                nav.push(Route::DocsPage { slug });
            }),
        };

        let providers = use_docs_providers(&*DOCS, docs_ctx);

        rsx! {
            DocsLayout {
                // Use providers.search_open / providers.drawer_open
                // in a custom header if needed
                Outlet::<Route> {}
            }
        }
    }

The DocsProviders struct returned by the hook gives you access to search_open and drawer_open signals for wiring up custom header buttons.

7

Add routes

Add the docs routes to your Route enum:

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

    #[component]
    fn DocsIndex() -> Element {
        rsx! { DocsPageContent {} }
    }

    #[component]
    fn DocsPage(slug: Vec<String>) -> Element {
        rsx! { DocsPageContent {} }
    }

What You Get

Once integrated, your docs site includes:

Sidebar Navigation

Auto-generated from _nav.json with tab switching and group headings

Full-Text Search

Built-in search modal (Cmd+K) across all doc content

API Reference

Two-column endpoint pages generated from OpenAPI specs

Page Navigation

Previous/next page links at the bottom of every page

Next Steps

Customization

Learn how to theme your site and configure navigation

Basic Usage

Explore all available MDX components

Navigation