dioxus_docs_kit/
lib.rs

1//! # dioxus-docs-kit
2//!
3//! Reusable documentation site shell for Dioxus applications.
4//!
5//! Provides a complete docs layout with sidebar navigation, search modal,
6//! page navigation, OpenAPI API reference pages, and mobile drawer.
7//!
8//! ## Quick Start
9//!
10//! ```rust,ignore
11//! use dioxus::prelude::*;
12//! use dioxus_docs_kit::{DocsConfig, DocsRegistry, DocsContext, DocsLayout, DocsPageContent};
13//! use std::sync::LazyLock;
14//!
15//! static DOCS: LazyLock<DocsRegistry> = LazyLock::new(|| {
16//!     DocsConfig::new(include_str!("../docs/_nav.json"), doc_content_map())
17//!         .with_openapi("api-reference", include_str!("../docs/api-reference/spec.yaml"))
18//!         // .with_api_group_name("My API Docs")  // must match a group in _nav.json
19//!         .build()
20//! });
21//!
22//! #[component]
23//! fn MyDocsLayout() -> Element {
24//!     let nav = use_navigator();
25//!     let route = use_route::<Route>();
26//!     let current_path = use_memo(move || /* extract path from route */);
27//!     let docs_ctx = DocsContext {
28//!         current_path: current_path.into(),
29//!         base_path: "/docs".into(),
30//!         navigate: Callback::new(move |path: String| { /* push route */ }),
31//!     };
32//!     use_context_provider(|| &*DOCS as &'static DocsRegistry);
33//!     use_context_provider(|| docs_ctx);
34//!     rsx! { DocsLayout {} }
35//! }
36//! ```
37
38pub mod components;
39pub mod config;
40pub mod hooks;
41pub mod registry;
42
43use dioxus::prelude::*;
44
45/// Navigation bridge that decouples library components from the consumer's Route enum.
46///
47/// The consumer creates this in their docs layout wrapper and provides it via `use_context_provider`.
48#[derive(Clone)]
49pub struct DocsContext {
50    /// Current docs page path (e.g. "getting-started/introduction").
51    pub current_path: ReadSignal<String>,
52    /// Base URL path for docs (e.g. "/docs").
53    pub base_path: String,
54    /// Callback to navigate to a docs page by content path.
55    pub navigate: Callback<String>,
56}
57
58// Re-export config and registry
59pub use config::{DocsConfig, ThemeConfig};
60pub use registry::DocsRegistry;
61
62// Re-export types consumers need
63pub use registry::{ApiEndpointEntry, NavConfig, NavGroup, SearchEntry};
64
65// Re-export UI components
66pub use components::{
67    CurrentTheme, DocsLayout, DocsPageContent, DocsPageNav, DocsSidebar, DrawerOpen, LayoutOffsets,
68    MobileDrawer, SearchButton, SearchModal, ThemeToggle,
69};
70
71// Re-export hooks
72pub use hooks::{DocsProviders, use_docs_providers};
73
74// Re-export key dioxus-mdx types that consumers commonly need
75pub use dioxus_mdx::{
76    ApiOperation, ApiTag, DocContent, DocTableOfContents, EndpointPage, HttpMethod, OpenApiSpec,
77    ParsedDoc, extract_headers, highlight_code,
78};
79
80#[cfg(feature = "mermaid")]
81pub use dioxus_mdx::MermaidDiagram;
82
83/// Generates a `doc_content_map()` function that returns a
84/// `HashMap<&'static str, &'static str>` from the build-script output.
85///
86/// Place this at module level in your `main.rs`:
87///
88/// ```rust,ignore
89/// dioxus_docs_kit::doc_content_map!();
90/// ```
91///
92/// Requires `dioxus-docs-kit-build` in `[build-dependencies]` and a `build.rs`
93/// that calls `dioxus_docs_kit_build::generate_content_map("docs/_nav.json")`.
94#[macro_export]
95macro_rules! doc_content_map {
96    () => {
97        fn doc_content_map() -> ::std::collections::HashMap<&'static str, &'static str> {
98            include!(concat!(env!("OUT_DIR"), "/doc_content_generated.rs"))
99        }
100    };
101}
dioxus_docs_kit/lib.rs

dioxus_docs_kit/
lib.rs
