dioxus_docs_kit/
lib.rs

1//! # dioxus-docs-kit
2//!
3//! Reusable documentation site shell and blog engine 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//! Also includes a full blog engine with post listing, tag filtering,
8//! search, reading time, and MDX rendering.
9//!
10//! ## Quick Start — Docs
11//!
12//! ```rust,ignore
13//! use dioxus::prelude::*;
14//! use dioxus_docs_kit::{DocsConfig, DocsRegistry, DocsContext, DocsLayout, DocsPageContent};
15//! use std::sync::LazyLock;
16//!
17//! static DOCS: LazyLock<DocsRegistry> = LazyLock::new(|| {
18//!     DocsConfig::new(include_str!("../docs/_nav.json"), doc_content_map())
19//!         .with_default_path("getting-started/introduction")
20//!         .build()
21//! });
22//! ```
23//!
24//! ## Quick Start — Blog
25//!
26//! ```rust,ignore
27//! use dioxus::prelude::*;
28//! use dioxus_docs_kit::{BlogConfig, BlogRegistry, BlogContext, BlogLayout, BlogList, BlogPostView};
29//! use std::sync::LazyLock;
30//!
31//! dioxus_docs_kit::blog_content_map!();
32//!
33//! static BLOG: LazyLock<BlogRegistry> = LazyLock::new(|| {
34//!     BlogConfig::new(include_str!("../blog/_blog.json"), blog_content_map())
35//!         .with_posts_per_page(9)
36//!         .build()
37//! });
38//! ```
39
40pub mod blog;
41pub mod components;
42pub mod config;
43pub mod hooks;
44pub mod registry;
45
46use dioxus::prelude::*;
47
48// ============================================================================
49// Docs context
50// ============================================================================
51
52/// Navigation bridge that decouples library components from the consumer's Route enum.
53///
54/// The consumer creates this in their docs layout wrapper and provides it via `use_context_provider`.
55#[derive(Clone)]
56pub struct DocsContext {
57    /// Current docs page path (e.g. "getting-started/introduction").
58    pub current_path: ReadSignal<String>,
59    /// Base URL path for docs (e.g. "/docs").
60    pub base_path: String,
61    /// Callback to navigate to a docs page by content path.
62    pub navigate: Callback<String>,
63}
64
65// ============================================================================
66// Blog context
67// ============================================================================
68
69/// Navigation bridge for blog pages, decoupled from the consumer's Route enum.
70///
71/// The consumer creates this in their blog layout wrapper and provides it via `use_context_provider`.
72#[derive(Clone)]
73pub struct BlogContext {
74    /// Current blog post slug (empty on the list/index page).
75    pub current_slug: ReadSignal<String>,
76    /// Base URL path for the blog (e.g. "/blog").
77    pub base_path: String,
78    /// Callback to navigate to a blog post by slug (empty string = blog index).
79    pub navigate: Callback<String>,
80    /// Optional full site URL for SEO meta tags (e.g. "https://example.com").
81    pub site_url: Option<String>,
82}
83
84// ============================================================================
85// Docs re-exports
86// ============================================================================
87
88pub use config::{DocsConfig, ThemeConfig};
89pub use registry::DocsRegistry;
90pub use registry::{ApiEndpointEntry, NavConfig, NavGroup, SearchEntry};
91
92pub use components::{
93    CurrentTheme, DocsLayout, DocsPageContent, DocsPageNav, DocsSidebar, DrawerOpen, LayoutOffsets,
94    MobileDrawer, SearchButton, SearchModal, ThemeToggle,
95};
96
97pub use hooks::{DocsProviders, use_docs_providers};
98
99pub use dioxus_mdx::{
100    ApiOperation, ApiTag, DocContent, DocTableOfContents, EndpointPage, HttpMethod, OpenApiSpec,
101    ParsedDoc, extract_headers, highlight_code,
102};
103
104#[cfg(feature = "mermaid")]
105pub use dioxus_mdx::MermaidDiagram;
106
107// ============================================================================
108// Blog re-exports
109// ============================================================================
110
111pub use blog::types::{Author, BlogFrontmatter, BlogPost, BlogSearchEntry};
112pub use blog::{BlogConfig, BlogProviders, BlogRegistry, use_blog_providers};
113
114pub use components::{
115    AuthorInfo, BlogCard, BlogIndexMeta, BlogLayout, BlogList, BlogMobileDrawer, BlogPostMeta,
116    BlogPostNav, BlogPostView, BlogSearchButton, BlogSearchModal, BlogThemeToggle,
117    ReadingProgressBar, ReadingTimeBadge, RelatedPosts, TagFilter,
118};
119
120// ============================================================================
121// Macros
122// ============================================================================
123
124/// Generates a `doc_content_map()` function that returns a
125/// `HashMap<&'static str, &'static str>` from the build-script output.
126///
127/// Place this at module level in your `main.rs`:
128///
129/// ```rust,ignore
130/// dioxus_docs_kit::doc_content_map!();
131/// ```
132///
133/// Requires `dioxus-docs-kit-build` in `[build-dependencies]` and a `build.rs`
134/// that calls `dioxus_docs_kit_build::generate_content_map("docs/_nav.json")`.
135#[macro_export]
136macro_rules! doc_content_map {
137    () => {
138        fn doc_content_map() -> ::std::collections::HashMap<&'static str, &'static str> {
139            include!(concat!(env!("OUT_DIR"), "/doc_content_generated.rs"))
140        }
141    };
142}
143
144/// Generates a `blog_content_map()` function that returns a
145/// `HashMap<&'static str, &'static str>` from the build-script output.
146///
147/// Place this at module level in your `main.rs`:
148///
149/// ```rust,ignore
150/// dioxus_docs_kit::blog_content_map!();
151/// ```
152///
153/// Requires `dioxus-docs-kit-build` in `[build-dependencies]` and a `build.rs`
154/// that calls `dioxus_docs_kit_build::generate_blog_content_map("blog/_blog.json")`.
155#[macro_export]
156macro_rules! blog_content_map {
157    () => {
158        fn blog_content_map() -> ::std::collections::HashMap<&'static str, &'static str> {
159            include!(concat!(env!("OUT_DIR"), "/blog_content_generated.rs"))
160        }
161    };
162}
dioxus_docs_kit/lib.rs

dioxus_docs_kit/
lib.rs
