dioxus_mdx/

lib.rs

//! # dioxus-mdx
//!
//! MDX parsing and rendering components for Dioxus applications.
//!
//! This crate provides a complete solution for rendering Mintlify-style MDX documentation
//! in Dioxus applications, including:
//!
//! - **Parser**: Extracts frontmatter, code blocks, and custom components from MDX
//! - **Components**: Pre-built Dioxus components for callouts, cards, tabs, steps, etc.
//! - **Syntax Highlighting**: Code blocks with language-aware highlighting
//!
//! ## Quick Start
//!
//! ```rust,ignore
//! use dioxus::prelude::*;
//! use dioxus_mdx::{parse_document, MdxContent};
//!
//! #[component]
//! fn DocsPage(content: String) -> Element {
//!     rsx! {
//!         MdxContent { content }
//!     }
//! }
//! ```
//!
//! ## Parsing Only
//!
//! If you want to parse MDX without using the components:
//!
//! ```rust
//! use dioxus_mdx::{parse_document, parse_mdx, DocNode};
//!
//! let mdx_content = r#"---
//! title: Getting Started
//! ---
//!
//! <Tip>This is a helpful tip!</Tip>
//!
//! ## Introduction
//!
//! Welcome to the documentation.
//! "#;
//!
//! // Parse with frontmatter
//! let doc = parse_document(mdx_content);
//! assert_eq!(doc.frontmatter.title, "Getting Started");
//!
//! // Parse content only
//! let nodes = parse_mdx("## Hello\n\n<Note>A note</Note>");
//! ```
//!
//! ## Supported Components
//!
//! - **Callouts**: `<Tip>`, `<Note>`, `<Warning>`, `<Info>`
//! - **Cards**: `<Card>`, `<CardGroup>`
//! - **Tabs**: `<Tabs>`, `<Tab>`
//! - **Steps**: `<Steps>`, `<Step>`
//! - **Accordion**: `<AccordionGroup>`, `<Accordion>`
//! - **Code**: `<CodeGroup>`, fenced code blocks with syntax highlighting
//! - **API Docs**: `<ParamField>`, `<ResponseField>`, `<Expandable>`
//! - **Examples**: `<RequestExample>`, `<ResponseExample>`
//! - **Changelog**: `<Update>`
//!
//! ## Styling
//!
//! Components use Tailwind CSS with DaisyUI classes. Ensure your project has
//! Tailwind and DaisyUI configured. The components use:
//!
//! - Base/neutral classes: `bg-base-200`, `text-base-content`, etc.
//! - Color classes: `text-primary`, `bg-success/10`, etc.
//! - Typography: `prose`, `prose-sm`
//!
//! ## Features
//!
//! - `web` (default): Enables web-specific features like clipboard copy
//! - `mermaid` (default): Renders ` ```mermaid ` fences as diagrams
//! - `highlight` (default): Syntax highlighting via `dioxus-code`
//! - `lang-*`: One tree-sitter grammar each. `highlight` alone highlights only
//!   Rust; the default set adds `lang-bash`, `lang-css`, `lang-dockerfile`,
//!   `lang-html`, `lang-javascript`, `lang-json`, `lang-markdown`,
//!   `lang-python`, `lang-toml`, `lang-typescript` and `lang-yaml`.
//!   `lang-c-sharp`, `lang-cpp` and `lang-tsx` exist but are off by default. For any other
//!   language, depend on `dioxus-code` directly with its `lang-*` flag
//!   (`features = ["runtime", "lang-go"]`); cargo unifies it into the copy this
//!   crate uses, so `Language::from_slug` resolves the grammar.
//!   A fence whose grammar is not compiled in renders as plain text.
//! - `openapi` (default): Parses OpenAPI specs — `parse_openapi` and inline
//!   `<OpenAPI>…</OpenAPI>` blocks. Turning it off drops `openapiv3` and
//!   `serde_yaml` from the build; the `OpenApiSpec` types and the viewer
//!   components stay, and an `<OpenAPI>` block renders as plain markdown.
//!
//! ## Custom Link Handling
//!
//! For internal navigation, components accept an `on_link` callback:
//!
//! ```rust,ignore
//! use dioxus::prelude::*;
//! use dioxus_mdx::DocCardGroup;
//!
//! #[component]
//! fn DocsPage(group: CardGroupNode) -> Element {
//!     let nav = use_navigator();
//!
//!     rsx! {
//!         DocCardGroup {
//!             group,
//!             on_link: move |href: String| nav.push(&href),
//!         }
//!     }
//! }
//! ```

pub mod components;
pub mod parser;
mod re;

// Re-export parser types and functions
pub use parser::{
    AccordionGroupNode, AccordionNode, ApiInfo, ApiOperation, ApiParameter, ApiRequestBody,
    ApiResponse, ApiServer, ApiTag, CalloutNode, CalloutType, CardGroupNode, CardNode,
    CodeBlockNode, CodeGroupNode, DocFrontmatter, DocNode, ExpandableNode, HttpMethod,
    MediaTypeContent, OpenApiNode, OpenApiSpec, ParamFieldNode, ParamLocation, ParameterLocation,
    ParsedDoc, RequestExampleNode, ResponseExampleNode, ResponseFieldNode, SchemaDefinition,
    SchemaType, StepNode, StepsNode, TabNode, TabsNode, UpdateNode, YamlLiteError, YamlMap,
    YamlValue, extract_frontmatter, get_raw_markdown, parse_document, parse_mdx, parse_yaml_lite,
    strip_leading_h1,
};

// Spec parsing lives behind the `openapi` feature (default); the `OpenApiSpec`
// types and the viewer components above are always available.
#[cfg(feature = "openapi")]
pub use parser::{OpenApiError, parse_openapi};

// Re-export the syntax-highlighting theme types so consumers can build a
// `CodeThemeOverride` without depending on `dioxus-code` directly. Only available
// with the `highlight` feature (default), which pulls in `dioxus-code`.
#[cfg(feature = "highlight")]
pub use dioxus_code::{CodeTheme, Theme};

// Re-export components
pub use components::{
    ApiInfoHeader, DocAccordionGroup, DocAccordionItem, DocCallout, DocCard, DocCardGroup,
    DocCodeBlock, DocCodeGroup, DocContent, DocExpandable, DocNodeRenderer, DocParamField,
    DocRequestExample, DocResponseExample, DocResponseField, DocSteps, DocTableOfContents, DocTabs,
    DocUpdate, EndpointCard, EndpointPage, MdxContent, MdxIcon, MdxRenderer, MethodBadge,
    OpenApiViewer, ParameterItem, ParametersList, RequestBodySection, ResponseItem, ResponsesList,
    SchemaDefinitions, SchemaTypeLabel, SchemaViewer, TagGroup, UngroupedEndpoints,
    extract_headers, slugify,
};

// `CodeThemeOverride` wraps a `dioxus-code` type, so it's only available with the
// `highlight` feature (default).
#[cfg(feature = "highlight")]
pub use components::CodeThemeOverride;

#[cfg(feature = "mermaid")]
pub use components::MermaidDiagram;