dioxus_docs_kit/

config.rs

//! Builder for constructing a `DocsRegistry`.

use crate::registry::DocsRegistry;
#[cfg(feature = "highlight")]
use dioxus_code::Theme;
use std::collections::HashMap;

/// Theme configuration for the documentation site.
///
/// Controls which DaisyUI theme(s) are applied and whether a toggle button is shown.
#[derive(Clone, Debug, PartialEq)]
pub struct ThemeConfig {
    /// The default theme name (must match a DaisyUI theme defined in `tailwind.css`).
    pub default_theme: String,
    /// If set, enables a light/dark toggle button. Tuple is `(light_theme, dark_theme)`.
    pub toggle_themes: Option<(String, String)>,
    /// localStorage key used to persist the user's theme preference.
    pub storage_key: String,
}

/// How rendered code blocks pick their syntax-highlighting theme.
///
/// Defaults to [`CodeThemeConfig::Adaptive`] with GitHub Light / Tokyo Night.
///
/// Only available with the `highlight` feature (default), which pulls in `dioxus-code`.
#[cfg(feature = "highlight")]
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub enum CodeThemeConfig {
    /// Always use this one theme, regardless of the site's light/dark state.
    Fixed(Theme),
    /// Pick `light` or `dark` to match the site theme.
    ///
    /// When a light/dark toggle is configured (via [`DocsConfig::with_theme_toggle`]),
    /// the choice tracks the active `data-theme` (not the OS `prefers-color-scheme`),
    /// so code blocks stay in sync with the toggle. Without a toggle it falls back to
    /// `prefers-color-scheme`.
    Adaptive {
        /// Theme used when the site is in its light state.
        light: Theme,
        /// Theme used when the site is in its dark state.
        dark: Theme,
    },
}

#[cfg(feature = "highlight")]
impl Default for CodeThemeConfig {
    fn default() -> Self {
        Self::Adaptive {
            light: Theme::GITHUB_LIGHT,
            dark: Theme::TOKYO_NIGHT,
        }
    }
}

/// Builder for constructing a [`DocsRegistry`].
///
/// # Example
///
/// ```rust,ignore
/// let registry = DocsConfig::new(nav_json, content_map)
///     // `.with_openapi()` needs the `openapi` feature (on by default)
///     .with_openapi("api-reference", spec_yaml)
///     .with_default_path("getting-started/introduction")
///     .build();
/// ```
pub struct DocsConfig {
    nav_json: String,
    content_map: HashMap<&'static str, &'static str>,
    #[cfg(feature = "openapi")]
    openapi_specs: Vec<(String, String)>,
    default_path: Option<String>,
    api_group_name: Option<String>,
    theme: Option<ThemeConfig>,
    #[cfg(feature = "highlight")]
    code_theme: CodeThemeConfig,
}

impl DocsConfig {
    /// Create a new builder from a `_nav.json` string and a content map.
    ///
    /// The content map is typically generated by `build.rs` using `include_str!()`.
    pub fn new(nav_json: &str, content_map: HashMap<&'static str, &'static str>) -> Self {
        Self {
            nav_json: nav_json.to_string(),
            content_map,
            #[cfg(feature = "openapi")]
            openapi_specs: Vec::new(),
            default_path: None,
            api_group_name: None,
            theme: None,
            #[cfg(feature = "highlight")]
            code_theme: CodeThemeConfig::default(),
        }
    }

    /// Add an OpenAPI specification.
    ///
    /// - `prefix`: The URL prefix for this spec's endpoints (e.g. "api-reference").
    /// - `yaml`: The raw YAML string of the OpenAPI spec.
    ///
    /// The `prefix` must correspond to a nav group in `_nav.json` whose `"group"` value
    /// matches [`Self::with_api_group_name`] (defaults to `"API Reference"`). The library
    /// dynamically injects API endpoints into that group's sidebar — do **not** list
    /// individual operation paths in the `"pages"` array of `_nav.json`.
    ///
    /// Only available with the `openapi` feature (default), which pulls in
    /// `openapiv3` and `serde_yaml`.
    #[cfg(feature = "openapi")]
    pub fn with_openapi(mut self, prefix: &str, yaml: &str) -> Self {
        self.openapi_specs
            .push((prefix.to_string(), yaml.to_string()));
        self
    }

    /// Set the default documentation path for redirects.
    ///
    /// Defaults to the first page in the first nav group if not set.
    pub fn with_default_path(mut self, path: &str) -> Self {
        self.default_path = Some(path.to_string());
        self
    }

    /// Set the display name for the API Reference sidebar group.
    ///
    /// Defaults to `"API Reference"`. The value must match a `"group"` in `_nav.json`
    /// so the library knows where to inject the API endpoint sidebar entries.
    /// See [`Self::with_openapi`] for details.
    pub fn with_api_group_name(mut self, name: &str) -> Self {
        self.api_group_name = Some(name.to_string());
        self
    }

    /// Set a single theme (no toggle button).
    ///
    /// The theme name must match a DaisyUI theme defined in the consumer's `tailwind.css`.
    pub fn with_theme(mut self, theme: &str) -> Self {
        self.theme = Some(ThemeConfig {
            default_theme: theme.to_string(),
            toggle_themes: None,
            storage_key: "docs-theme".to_string(),
        });
        self
    }

    /// Enable a light/dark theme toggle.
    ///
    /// - `light`: Name of the light DaisyUI theme.
    /// - `dark`: Name of the dark DaisyUI theme.
    /// - `default`: Which of the two to use on first visit (`light` or `dark`).
    pub fn with_theme_toggle(mut self, light: &str, dark: &str, default: &str) -> Self {
        self.theme = Some(ThemeConfig {
            default_theme: default.to_string(),
            toggle_themes: Some((light.to_string(), dark.to_string())),
            storage_key: "docs-theme".to_string(),
        });
        self
    }

    /// Use a single, fixed syntax-highlighting theme for all code blocks.
    ///
    /// Use this for single-theme sites (e.g. a dark-only app) so the code block
    /// background matches the site instead of following the reader's OS setting.
    ///
    /// Only available with the `highlight` feature (default), which pulls in `dioxus-code`.
    #[cfg(feature = "highlight")]
    pub fn with_code_theme(mut self, theme: Theme) -> Self {
        self.code_theme = CodeThemeConfig::Fixed(theme);
        self
    }

    /// Use a light/dark pair of syntax themes for code blocks.
    ///
    /// When a theme toggle is configured (see [`Self::with_theme_toggle`]), the active
    /// choice tracks the toggle's `data-theme`; otherwise it follows the reader's OS
    /// `prefers-color-scheme`. Defaults to GitHub Light / Tokyo Night when not set.
    ///
    /// Only available with the `highlight` feature (default), which pulls in `dioxus-code`.
    #[cfg(feature = "highlight")]
    pub fn with_code_themes(mut self, light: Theme, dark: Theme) -> Self {
        self.code_theme = CodeThemeConfig::Adaptive { light, dark };
        self
    }

    /// Build the [`DocsRegistry`].
    ///
    /// Parses all documents, builds the search index, and parses OpenAPI specs.
    ///
    /// # Panics
    ///
    /// Panics with a descriptive message if `_nav.json` or an OpenAPI spec fails
    /// to parse. Use [`Self::try_build`] to handle these errors yourself.
    pub fn build(self) -> DocsRegistry {
        self.try_build()
            .unwrap_or_else(|e| panic!("dioxus-docs-kit: {e}"))
    }

    /// Build the [`DocsRegistry`], returning an error instead of panicking when
    /// `_nav.json` or an OpenAPI spec fails to parse.
    pub fn try_build(self) -> Result<DocsRegistry, crate::error::DocsKitError> {
        DocsRegistry::try_from_config(self)
    }

    // Accessors for DocsRegistry::from_config
    pub(crate) fn nav_json(&self) -> &str {
        &self.nav_json
    }

    pub(crate) fn content_map(&self) -> &HashMap<&'static str, &'static str> {
        &self.content_map
    }

    #[cfg(feature = "openapi")]
    pub(crate) fn openapi_specs(&self) -> &[(String, String)] {
        &self.openapi_specs
    }

    pub(crate) fn default_path_value(&self) -> Option<&str> {
        self.default_path.as_deref()
    }

    pub(crate) fn api_group_name_value(&self) -> Option<&str> {
        self.api_group_name.as_deref()
    }

    pub(crate) fn theme_config(&self) -> Option<&ThemeConfig> {
        self.theme.as_ref()
    }

    #[cfg(feature = "highlight")]
    pub(crate) fn code_theme_value(&self) -> CodeThemeConfig {
        self.code_theme
    }
}