Skip to content

themeconfig

Class info

Classes

Name Children Inherits
ThemeConfig
mkdocs_mknodes.appconfig.themeconfig
Configuration settings for the MkDocs themes.

    🛈 DocStrings

    Pydantic types for universal_pathlib (upath.UPath) with validation capabilities.

    This module provides a Pydantic-compatible type for upath.UPath, offering similar functionality to Pydantic's built-in Path type. It includes validators for existence checks and path type verification.

    Example 
    from pydantic import BaseModel

class Config(BaseModel):
    input_file: UPathFile
    output_dir: UPathDir
    temp_path: UPath

# Usage
config = Config(
    input_file="data.csv",
    output_dir="output",
    temp_path="temp/workspace"
)

    ThemeConfig

    Bases: BaseModel

    Configuration settings for the MkDocs themes.

    Theme Configuration Options

    The theme configuration allows for extensive customization including custom directories, static templates, and locale settings.

    Properties Overview

    Property Description Required
    name Theme identifier Yes
    custom_dir Custom theme directory No
    static_templates Additional static pages No
    locale Language/locale setting No

    Parameters:

    Name Type Description Default
    name str
    		'material'
    custom_dir str | None
    		None
    static_templates list[str] | None
    		[]
    locale str | None
    		'en'
    Source code in mkdocs_mknodes/appconfig/themeconfig.py 
     34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
    class ThemeConfig(BaseModel):
    """Configuration settings for the MkDocs themes.

    !!! info "Theme Configuration Options"
        The theme configuration allows for extensive customization including custom
        directories, static templates, and locale settings.

    ## Properties Overview

    | Property | Description | Required |
    |----------|-------------|----------|
    | name | Theme identifier | Yes |
    | custom_dir | Custom theme directory | No |
    | static_templates | Additional static pages | No |
    | locale | Language/locale setting | No |
    """

    name: str = Field("material")
    """Specifies the theme to use for documentation rendering.

    !!! info "Common Theme Options"
        - `material`: Material for MkDocs theme
        - `mkdocs`: Default MkDocs theme
        - `readthedocs`: ReadTheDocs theme

    !!! example "Basic Configuration"
        ```yaml
        theme:
          name: material
        ```
    """
    # pydantic.DirectoryPath would be better
    custom_dir: str | None = Field(None)
    """Directory containing custom theme overrides or extensions.

    !!! tip "Theme Customization"
        Use this to override or extend the selected theme's templates and assets.

    !!! example "Custom Directory Setup"
        ```yaml
        theme:
          name: material
          custom_dir: custom_theme/
        ```
    """

    static_templates: list[str] | None = Field(default_factory=list)
    """Defines templates to be rendered as static pages, regardless of nav structure.

    !!! info "Common Use Cases"
        - Error pages (404, 500)
        - Sitemaps
        - Custom static pages

    !!! example "Static Templates Configuration"
        ```yaml
        theme:
          name: material
          static_templates:
            - sitemap.html
            - 404.html
            - custom_page.html
        ```
    """

    locale: str | None = Field("en")
    """Defines the language and regional settings for the theme.

    !!! info "Locale Impact"
        Affects:
        - Date formats
        - UI text translations
        - RTL/LTR text direction

    !!! example "Locale Setting"
        ```yaml
        theme:
          name: material
          locale: en_US
        ```

    !!! tip "Common Locales"
        - `en_US`: English (United States)
        - `fr_FR`: French (France)
        - `de_DE`: German (Germany)
        - `ja_JP`: Japanese (Japan)
    """
    # Material-related
    # palette: dict[str, Any] | None = Field(
    #     None, description="Color palette configuration for the theme."
    # )
    # font: dict[str, Any] | None = Field(
    #     None, description="Font configuration for the theme."
    # )
    # features: list[str] | None = Field(
    #     None, description="List of theme-specific features to enable."
    # )
    # logo: str | None = Field(None, description="Path to a logo file for the theme.")
    # icon: str | None = Field(None, description="Path to a favicon file.")
    # favicon: str | None = Field(None, description="Path to a favicon file.")
    # language: str | None = Field(None, description="Language for theme localization.")

    @model_validator(mode="before")
    @classmethod
    def validate_theme_config(
        cls, data: Self | dict[str, Any] | str
    ) -> Self | dict[str, Any]:
        if isinstance(data, cls):
            # Return the ThemeConfig instance as is
            return data
        if isinstance(data, str):
            # Initialize ThemeConfig with name=string
            return {"name": data}
        if isinstance(data, dict):
            # Validate using the standard model validation
            return data
        msg = "ThemeConfig must be a str, ThemeConfig instance, or dict"
        raise TypeError(msg)

    custom_dir class-attribute instance-attribute 

    custom_dir: str | None = Field(None)

    Directory containing custom theme overrides or extensions.

    Theme Customization

    Use this to override or extend the selected theme's templates and assets.

    Custom Directory Setup

    theme:
  name: material
  custom_dir: custom_theme/

    locale class-attribute instance-attribute 

    locale: str | None = Field('en')

    Defines the language and regional settings for the theme.

    Locale Impact

    Affects: - Date formats - UI text translations - RTL/LTR text direction

    Locale Setting

    theme:
  name: material
  locale: en_US

    Common Locales

    • en_US: English (United States)
    • fr_FR: French (France)
    • de_DE: German (Germany)
    • ja_JP: Japanese (Japan)

    name class-attribute instance-attribute 

    name: str = Field('material')

    Specifies the theme to use for documentation rendering.

    Common Theme Options

    • material: Material for MkDocs theme
    • mkdocs: Default MkDocs theme
    • readthedocs: ReadTheDocs theme

    Basic Configuration

    theme:
  name: material

    static_templates class-attribute instance-attribute 

    static_templates: list[str] | None = Field(default_factory=list)

    Defines templates to be rendered as static pages, regardless of nav structure.

    Common Use Cases

    • Error pages (404, 500)
    • Sitemaps
    • Custom static pages

    Static Templates Configuration

    theme:
  name: material
  static_templates:
    - sitemap.html
    - 404.html
    - custom_page.html