dioxus-docs-kit 0.3.0

# dioxus-docs-kit

Reusable documentation site kit for [Dioxus](https://dioxuslabs.com/) 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](https://crates.io/crates/dioxus-mdx) for content rendering.

## Quick Start

Add to your `Cargo.toml`:

```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:

```rust
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:

```rust
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

```rust
#[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

| Component | Description |
|-----------|-------------|
| `DocsLayout` | Full page layout with sidebar, content area, and table of contents |
| `DocsSidebar` | Navigation sidebar built from `_nav.json` |
| `DocsPageContent` | Renders MDX docs or OpenAPI endpoint pages |
| `DocsPageNav` | Previous/next page navigation |
| `SearchModal` | Full-text search across all docs |
| `SearchButton` | Trigger button for the search modal |
| `MobileDrawer` | Mobile navigation drawer |
| `ThemeToggle` | Light/dark theme switcher |

## Navigation Config

Define your docs structure in `_nav.json`:

```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](https://github.com/hauju/dioxus-docs-kit) for a complete `build.rs` implementation.

## Styling Setup

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

### Install dependencies

```sh
bun add tailwindcss @tailwindcss/typography daisyui
```

### Configure Tailwind

Add to your `tailwind.css`:

```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:

```css
@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:

```css
@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