mkdocs-mknodes 0.5.4__tar.gz → 0.7.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. mkdocs_mknodes-0.7.2/.github/workflows/documentation.yml +68 -0
  2. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.pre-commit-config.yaml +2 -2
  3. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/PKG-INFO +2 -3
  4. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/__init__.py +1 -1
  5. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/appconfig.py +202 -161
  6. mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/base.py +64 -0
  7. mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/jinjaconfig.py +60 -0
  8. mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/themeconfig.py +179 -0
  9. mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/upathtype.py +178 -0
  10. mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/validationconfig.py +41 -0
  11. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/builders/configbuilder.py +3 -4
  12. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/cli/__init__.py +15 -14
  13. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/build_page.py +73 -19
  14. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/serve.py +12 -8
  15. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/utils.py +5 -5
  16. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/liveserver.py +9 -27
  17. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/use_cases_section.py +3 -4
  18. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/mkdocsconfig.py +5 -15
  19. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/__init__.py +13 -5
  20. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +8 -3
  21. mkdocs_mknodes-0.7.2/mkdocs_mknodes/plugin/mknodesconfig.py +342 -0
  22. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/pluginconfig.py +2 -1
  23. mkdocs_mknodes-0.7.2/mkdocs_mknodes/resources/mkdocs_basic.yml +14 -0
  24. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/pyproject.toml +2 -0
  25. mkdocs_mknodes-0.5.4/.github/workflows/documentation.yml +0 -68
  26. mkdocs_mknodes-0.5.4/mkdocs_mknodes/mknodesconfig.py +0 -106
  27. mkdocs_mknodes-0.5.4/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -35
  28. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.editorconfig +0 -0
  29. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/README.md +0 -0
  30. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/copilot-instructions.md +0 -0
  31. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/dependabot.yml +0 -0
  32. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/workflows/build.yml +0 -0
  33. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.gitignore +0 -0
  34. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/LICENSE +0 -0
  35. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/README.md +0 -0
  36. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/configs/mkdocs_mkdocs.yml +0 -0
  37. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/configs/mkdocs_shared.yml +0 -0
  38. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/assets/cli.gif +0 -0
  39. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/build_process.jinja +0 -0
  40. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/cli_index.jinja +0 -0
  41. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/github_index.jinja +0 -0
  42. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/index.jinja +0 -0
  43. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/plugin_configuration.jinja +0 -0
  44. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/use_case_by_config.jinja +0 -0
  45. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/use_case_default_website.jinja +0 -0
  46. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/use_cases_index.jinja +0 -0
  47. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/why_should_i_use_mknodes.jinja +0 -0
  48. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/duties.py +0 -0
  49. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs.yml +0 -0
  50. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/__init__.py +0 -0
  51. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/__init__.py +0 -0
  52. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
  53. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
  54. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
  55. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/buildcollector.py +0 -0
  56. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/buildcontext.py +0 -0
  57. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/builders/__init__.py +0 -0
  58. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/cli/richstate.py +0 -0
  59. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/__init__.py +0 -0
  60. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/__init__.py +0 -0
  61. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
  62. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
  63. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/github_index.py +0 -0
  64. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/root.py +0 -0
  65. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
  66. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/paths.py +0 -0
  67. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
  68. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
  69. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/py.typed +0 -0
  70. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
  71. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/telemetry.py +0 -0
  72. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes.sublime-project +0 -0
  73. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/overrides/_dummy.txt +0 -0
  74. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/overrides/partials/actions.html +0 -0
  75. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/__init__.py +0 -0
  76. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/conftest.py +0 -0
  77. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/data/objects.inv +0 -0
  78. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/test_build.py +0 -0
  79. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/test_cli.py +0 -0
@@ -0,0 +1,68 @@
1
+ name: Build documentation
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+
8
+ # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
9
+ permissions:
10
+ contents: read
11
+ pages: write
12
+ id-token: write
13
+
14
+ # Allow one concurrent deployment
15
+ concurrency:
16
+ group: "pages"
17
+ cancel-in-progress: true
18
+
19
+ # Default to bash
20
+ defaults:
21
+ run:
22
+ shell: bash
23
+
24
+ jobs:
25
+ build:
26
+ runs-on: ubuntu-latest
27
+
28
+ steps:
29
+ - name: Check out repository
30
+ uses: actions/checkout@v4
31
+ with:
32
+ fetch-depth: 0
33
+
34
+ - name: Set up Python 3.12
35
+ uses: actions/setup-python@v5
36
+ with:
37
+ python-version: "3.12"
38
+
39
+ - name: Setup Graphviz
40
+ uses: ts-graphviz/setup-graphviz@v2
41
+
42
+ - name: Install uv
43
+ uses: yezz123/setup-uv@v4
44
+
45
+ - name: Install dependencies
46
+ run: uv sync --all-extras
47
+
48
+ - name: Build main documentation page
49
+ run: uv run mknodes build -v
50
+
51
+ - name: Build example sub-page (MkDocs)
52
+ run: uv run mknodes build -d ../site/mkdocs -p configs/mkdocs_mkdocs.yml -v --clone-depth 100
53
+
54
+ - name: Package and upload page artifact
55
+ uses: actions/upload-pages-artifact@v3
56
+ with:
57
+ path: ./site
58
+
59
+ deploy:
60
+ environment:
61
+ name: github-pages
62
+ url: ${{ steps.deployment.outputs.page_url }}
63
+ runs-on: ubuntu-latest
64
+ needs: build
65
+ steps:
66
+ - name: Deploy to GitHub Pages
67
+ id: deployment
68
+ uses: actions/deploy-pages@v4
@@ -33,10 +33,10 @@ repos:
33
33
  hooks:
34
34
  - id: mypy
35
35
  # args: [--ignore-missing-imports]
36
- additional_dependencies: [mkdocs, orjson]
36
+ additional_dependencies: [mkdocs, orjson, pydantic]
37
37
 
38
38
  - repo: https://github.com/charliermarsh/ruff-pre-commit
39
- rev: v0.7.1
39
+ rev: v0.7.3
40
40
  hooks:
41
41
  - id: ruff
42
42
  - id: ruff-format
@@ -1,13 +1,11 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: mkdocs-mknodes
3
- Version: 0.5.4
3
+ Version: 0.7.2
4
4
  Summary: Don't write docs. Code them.
5
5
  Project-URL: Documentation, https://phil65.github.io/mkdocs-mknodes/
6
6
  Project-URL: Source, https://github.com/phil65/mkdocs_mknodes
7
7
  Project-URL: Gitter, https://app.gitter.im/#/room/#mknodes:gitter.im
8
8
  Author-email: Philipp Temminghoff <philipptemminghoff@gmail.com>
9
- License-Expression: MIT
10
- License-File: LICENSE
11
9
  Keywords: docs,docstrings,documentation,framework,internet,markdown
12
10
  Classifier: Development Status :: 4 - Beta
13
11
  Classifier: Intended Audience :: Developers
@@ -37,6 +35,7 @@ Requires-Dist: rich
37
35
  Requires-Dist: typer
38
36
  Requires-Dist: universal-pathlib
39
37
  Requires-Dist: yamling
38
+ Requires-Dist: yarl>=1.17.1
40
39
  Description-Content-Type: text/markdown
41
40
 
42
41
  ``` py title='__main__.create_github_index_md' linenums="86" hl_lines="3"
@@ -1,4 +1,4 @@
1
- __version__ = "0.5.4"
1
+ __version__ = "0.7.2"
2
2
 
3
3
 
4
4
  from .mkdefaultwebsite import MkDefaultWebsite
@@ -1,16 +1,31 @@
1
1
  from __future__ import annotations
2
2
 
3
+ from collections.abc import Callable
4
+ import functools
3
5
  import ipaddress
4
6
  from typing import Annotated, Any
5
7
 
8
+ from mknodes.utils import classhelpers
6
9
  from pathspec import gitignore
7
- from pydantic import BaseModel, DirectoryPath, Field, FilePath, HttpUrl, field_validator
10
+ from pydantic import (
11
+ BaseModel,
12
+ DirectoryPath,
13
+ Field,
14
+ HttpUrl,
15
+ ValidationInfo,
16
+ field_validator,
17
+ )
8
18
  from pydantic.functional_validators import BeforeValidator
9
19
  from pydantic_core import PydanticCustomError
10
20
 
21
+ from mkdocs_mknodes.appconfig import jinjaconfig, themeconfig, validationconfig
22
+ from mkdocs_mknodes.appconfig.base import ConfigFile
11
23
 
12
- def validate_gitignore_patterns(patterns: list[str]) -> list[str]:
24
+
25
+ def validate_gitignore_patterns(pattern: list[str] | str) -> str:
13
26
  """Validate a list of gitignore patterns using pathspec."""
27
+ patterns = pattern.splitlines() if isinstance(pattern, str) else pattern
28
+ pattern_str = pattern if isinstance(pattern, str) else "\n".join(pattern)
14
29
  try:
15
30
  gitignore.GitIgnoreSpec.from_lines(patterns)
16
31
  except Exception as e:
@@ -21,11 +36,11 @@ def validate_gitignore_patterns(patterns: list[str]) -> list[str]:
21
36
  {"error": str(e)},
22
37
  ) from e
23
38
  else:
24
- return patterns
39
+ return pattern_str
25
40
 
26
41
 
27
42
  GitIgnorePatterns = Annotated[
28
- list[str],
43
+ str,
29
44
  BeforeValidator(validate_gitignore_patterns),
30
45
  ]
31
46
 
@@ -39,109 +54,6 @@ class NavItem(BaseModel):
39
54
  item: str | dict[str, NavItem]
40
55
 
41
56
 
42
- class ThemeConfig(BaseModel):
43
- """Configuration settings for the MkDocs themes.
44
-
45
- !!! info "Theme Configuration Options"
46
- The theme configuration allows for extensive customization including custom
47
- directories, static templates, and locale settings.
48
-
49
- ## Properties Overview
50
-
51
- | Property | Description | Required |
52
- |----------|-------------|----------|
53
- | name | Theme identifier | Yes |
54
- | custom_dir | Custom theme directory | No |
55
- | static_templates | Additional static pages | No |
56
- | locale | Language/locale setting | No |
57
- """
58
-
59
- name: str = Field(...)
60
- """Specifies the theme to use for documentation rendering.
61
-
62
- !!! info "Common Theme Options"
63
- - `material`: Material for MkDocs theme
64
- - `mkdocs`: Default MkDocs theme
65
- - `readthedocs`: ReadTheDocs theme
66
-
67
- !!! example "Basic Configuration"
68
- ```yaml
69
- theme:
70
- name: material
71
- ```
72
- """
73
-
74
- custom_dir: DirectoryPath | None = Field(None)
75
- """Directory containing custom theme overrides or extensions.
76
-
77
- !!! tip "Theme Customization"
78
- Use this to override or extend the selected theme's templates and assets.
79
-
80
- !!! example "Custom Directory Setup"
81
- ```yaml
82
- theme:
83
- name: material
84
- custom_dir: custom_theme/
85
- ```
86
- """
87
-
88
- static_templates: list[str] | None = Field(None)
89
- """Defines templates to be rendered as static pages, regardless of nav structure.
90
-
91
- !!! info "Common Use Cases"
92
- - Error pages (404, 500)
93
- - Sitemaps
94
- - Custom static pages
95
-
96
- !!! example "Static Templates Configuration"
97
- ```yaml
98
- theme:
99
- name: material
100
- static_templates:
101
- - sitemap.html
102
- - 404.html
103
- - custom_page.html
104
- ```
105
- """
106
-
107
- locale: str | None = Field(None)
108
- """Defines the language and regional settings for the theme.
109
-
110
- !!! info "Locale Impact"
111
- Affects:
112
- - Date formats
113
- - UI text translations
114
- - RTL/LTR text direction
115
-
116
- !!! example "Locale Setting"
117
- ```yaml
118
- theme:
119
- name: material
120
- locale: en_US
121
- ```
122
-
123
- !!! tip "Common Locales"
124
- - `en_US`: English (United States)
125
- - `fr_FR`: French (France)
126
- - `de_DE`: German (Germany)
127
- - `ja_JP`: Japanese (Japan)
128
- """
129
- # Material-related
130
- # palette: dict[str, Any] | None = Field(
131
- # None, description="Color palette configuration for the theme."
132
- # )
133
- # font: dict[str, Any] | None = Field(
134
- # None, description="Font configuration for the theme."
135
- # )
136
- # features: list[str] | None = Field(
137
- # None, description="List of theme-specific features to enable."
138
- # )
139
- # logo: str | None = Field(None, description="Path to a logo file for the theme.")
140
- # icon: str | None = Field(None, description="Path to a favicon file.")
141
- # favicon: str | None = Field(None, description="Path to a favicon file.")
142
- # language: str | None = Field(None, description="Language for theme localization.")
143
-
144
-
145
57
  class PluginConfig(BaseModel):
146
58
  """Configuration for a MkDocs plugin."""
147
59
 
@@ -151,7 +63,14 @@ class PluginConfig(BaseModel):
151
63
  )
152
64
 
153
65
 
154
- class AppConfig(BaseModel):
66
+ class ExtraJavascript(BaseModel):
67
+ path: str
68
+ type: str | None = None
69
+ async_: bool | None = Field(None, alias="async")
70
+ defer: bool | None = None
71
+
72
+
73
+ class AppConfig(ConfigFile):
155
74
  """The main configuration class for MkDocs projects.
156
75
 
157
76
  This class defines all available settings for customizing your documentation site.
@@ -180,7 +99,7 @@ class AppConfig(BaseModel):
180
99
  ```
181
100
  """
182
101
 
183
- site_url: HttpUrl | None = Field(None)
102
+ site_url: str | None = Field(None)
184
103
  """The canonical URL for your documentation site.
185
104
 
186
105
  !!! info "Purpose"
@@ -323,6 +242,83 @@ class AppConfig(BaseModel):
323
242
  - Staging environments
324
243
  """
325
244
 
245
+ build_fn: str = "mkdocs_mknodes:parse"
246
+ """Path to the build script / callable.
247
+
248
+ Possible formats:
249
+
250
+ - `my.module:Class.build_fn` (must be a classmethod / staticmethod)
251
+ - `my.module:build_fn`
252
+ - `path/to/file.py:build_fn`
253
+
254
+ Can also be remote.
255
+ The targeted callable gets the project instance as an argument and optionally
256
+ keyword arguments from setting below.
257
+ """
258
+ build_fn_arguments: dict[str, Any] | None = None
259
+ """Keyword arguments passed to the build script / callable.
260
+
261
+ Build scripts may have keyword arguments. You can set them by using this setting.
262
+ """
263
+ repo_path: str = "."
264
+ """Path to the repository to create a website for. (`http://....my_project.git`)"""
265
+ clone_depth: int = 100
266
+ """Clone depth in case the repository is remote. (Required for `git-changelog`)."""
267
+ build_folder: str | None = None
268
+ """Folder to create the Markdown files in.
269
+
270
+ If no folder is set, **MkNodes** will generate a temporary dir."""
271
+ show_page_info: bool = True
272
+ """Append an admonition box with build-related information.
273
+
274
+ If True, all pages get added an expandable admonition box at the bottom,
275
+ containing information about the created page.
276
+ This includes:
277
+ - Metadata
278
+ - Resources
279
+ - Code which created the page (needs the page to be created via decorators, or
280
+ the `generated_by` attribute of the `MkPage` needs to be set manually)
281
+ """
282
+ rewrite_theme_templates: bool = True
283
+ """Add additional functionality to themes by rewriting template files.
284
+
285
+ MkNodes can rewrite the HTML templates of Themes in order to add additional
286
+ functionality.
287
+
288
+ Right now, enabling this feature allows these options for the **Material-MkDocs**
289
+ theme:
290
+ - use iconify icons instead of the **Material-MkDocs** icons
291
+ - setting the theme features "navigation.indexes" and "navigation.expand" via
292
+ page metadata.
293
+ """
294
+ auto_delete_generated_templates: bool = True
295
+ """Delete the generated HTML templates when build is finished.
296
+
297
+ MkNodes may generate HTML template overrides during the build process and
298
+ deletes them after build. Using this setting, the deletion can be prevented.
299
+ """
300
+ render_by_default: bool = True
301
+ """Render all pages in the jinja environment.
302
+
303
+ This allows to render jinja in the **MkNodes** environment outside of the `MkJinja`
304
+ nodes.
305
+
306
+ This setting can be overridden by setting the page metadata field "render_macros".
307
+ """
308
+ global_resources: bool = True
309
+ """Make resources globally available.
310
+
311
+ If True, then the resources inferred from the nodes will be put into all HTML pages.
312
+ (This reflects the "default" MkDocs mechanism of putting extra CSS / JS into the
313
+ config file)
314
+ If False, then MkNodes will put the CSS / JS only into the pages which need it.
315
+ (the resources will be moved into the appropriate page template blocks)
316
+ """
317
+ jinja_config: jinjaconfig.JinjaConfig = Field(default_factory=jinjaconfig.JinjaConfig)
318
+ """Contains the configuration for the Jinja2 Environment.
319
+
320
+ Allows setting up loaders, extensions and the render behavior.
321
+ """
326
322
  docs_dir: DirectoryPath = Field("docs")
327
323
  """Directory containing documentation markdown source files.
328
324
 
@@ -386,7 +382,7 @@ class AppConfig(BaseModel):
386
382
  ```
387
383
  """
388
384
 
389
- theme: ThemeConfig = Field(...)
385
+ theme: themeconfig.ThemeConfig = Field(default_factory=themeconfig.ThemeConfig)
390
386
  """The MkDocs theme for the documentation.
391
387
 
392
388
  Can be a string for built-in themes or a theme config dict.
@@ -465,8 +461,8 @@ class AppConfig(BaseModel):
465
461
  dev_addr: localhost:8080 # alternate port
466
462
  ```
467
463
  """
468
-
469
- extra_css: list[FilePath] | None = Field(None)
464
+ # pydantic.FilePath would be nice.. Looses bw compat to old mkdocs filess
465
+ extra_css: list[str] | None = Field(None)
470
466
  """Custom CSS files to include in the documentation.
471
467
 
472
468
  !!! info "Processing"
@@ -488,7 +484,7 @@ class AppConfig(BaseModel):
488
484
  ```
489
485
  """
490
486
 
491
- extra_javascript: list[FilePath] | None = Field(None)
487
+ extra_javascript: list[str | ExtraJavascript] | None = Field(None)
492
488
  """Custom JavaScript files to include in the documentation.
493
489
 
494
490
  !!! info "File Types"
@@ -511,7 +507,7 @@ class AppConfig(BaseModel):
511
507
  Scripts are loaded after theme JavaScript files
512
508
  """
513
509
 
514
- markdown_extensions: list[str | dict[str, Any]] | None = Field(None)
510
+ markdown_extensions: list[dict[str, Any]] | None = Field(None)
515
511
  """PyMarkdown extensions and their configurations.
516
512
 
517
513
  !!! info "Default Extensions"
@@ -571,7 +567,7 @@ class AppConfig(BaseModel):
571
567
  ```
572
568
  """
573
569
 
574
- nav: list[NavItem] | None = Field(None)
570
+ nav: list[dict[str, Any] | str] | None = Field(None)
575
571
  """Defines the hierarchical structure of the documentation navigation.
576
572
  Each item can be a simple path to a file or a section with nested items.
577
573
 
@@ -604,27 +600,7 @@ class AppConfig(BaseModel):
604
600
  ```
605
601
  """
606
602
 
607
- language: str | None = Field(None)
608
- """The language of the documentation as a BCP 47 language tag.
609
-
610
- Example in mkdocs.yml:
611
- ```yaml
612
- language: en
613
- ```
614
- """
615
-
616
- locale: str | None = Field(None)
617
- """The locale of the documentation.
618
-
619
- Affects date formats and other regional settings.
620
-
621
- Example in mkdocs.yml:
622
- ```yaml
623
- locale: en_US
624
- ```
625
- """
626
-
627
- extra: dict[str, Any] | None = Field(None)
603
+ extra: dict[str, Any] = Field(default_factory=dict)
628
604
  """A mapping/dictionary of custom data that is passed to the template.
629
605
 
630
606
  This allows template authors to require extra configuration that is not
@@ -641,7 +617,7 @@ class AppConfig(BaseModel):
641
617
  ```
642
618
  """
643
619
 
644
- validation: dict[str, Any] | None = Field(None)
620
+ validation: validationconfig.ValidationConfig | None = Field(None)
645
621
  """Controls the validation behavior for links, content, and navigation.
646
622
 
647
623
  !!! info "Validation Levels"
@@ -672,8 +648,8 @@ class AppConfig(BaseModel):
672
648
  omitted_files: strict
673
649
  ```
674
650
  """
675
-
676
- watch: list[DirectoryPath] | None = Field(None)
651
+ # DirectoryPath would be nice
652
+ watch: list[str] | None = Field(None)
677
653
  """Additional directories to monitor for changes during development.
678
654
 
679
655
  !!! info "Behavior"
@@ -690,7 +666,7 @@ class AppConfig(BaseModel):
690
666
  ```
691
667
  """
692
668
 
693
- exclude_docs: GitIgnorePatterns = Field(default_factory=list)
669
+ exclude_docs: GitIgnorePatterns = Field(default="")
694
670
  """Gitignore-style patterns for files to exclude from documentation.
695
671
 
696
672
  !!! info "Pattern Syntax"
@@ -713,7 +689,7 @@ class AppConfig(BaseModel):
713
689
  Patterns are relative to `docs_dir`
714
690
  """
715
691
 
716
- not_in_nav: GitIgnorePatterns = Field(default_factory=list)
692
+ not_in_nav: GitIgnorePatterns = Field(default="")
717
693
  """Patterns for files that should not generate warnings when not in navigation.
718
694
 
719
695
  !!! info "Use Cases"
@@ -737,26 +713,55 @@ class AppConfig(BaseModel):
737
713
  - Referenced programmatically
738
714
  """
739
715
 
740
- @field_validator("plugins", mode="before")
716
+ @field_validator("plugins", "markdown_extensions", mode="before")
741
717
  @classmethod
742
718
  def convert_to_plugin_dict_list(
743
719
  cls,
744
720
  value: list[str | dict[str, dict[str, Any]]] | dict[str, Any],
721
+ info: ValidationInfo,
745
722
  ) -> list[dict[str, dict[str, Any]]]:
746
723
  result: list[dict[str, Any]] = []
747
- for item in value:
748
- if isinstance(item, str):
749
- result.append({item: {}})
750
- elif isinstance(item, dict):
751
- if len(item) > 1:
752
- msg = "Plugin dictionaries must have a single key"
753
- raise ValueError(msg)
754
- result.append(item)
755
- else:
756
- msg = f"Invalid type for plugin section: {item!r} ({type(item)})"
757
- raise ValueError(msg) # noqa: TRY004
724
+ match value:
725
+ case dict():
726
+ # Convert dict to list of single-key dicts
727
+ for k, v in value.items():
728
+ result.append({k: v})
729
+ case list():
730
+ for item in value:
731
+ match item:
732
+ case str():
733
+ result.append({item: {}})
734
+ case dict():
735
+ if len(item) > 1:
736
+ f = info.field_name
737
+ msg = f"{f} dictionaries must have a single key"
738
+ raise ValueError(msg)
739
+ result.append(item)
740
+ case _:
741
+ type_str = f"{item!r} ({type(item)})"
742
+ f = info.field_name
743
+ msg = f"Invalid type for {f} section: {type_str}"
744
+ raise ValueError(msg)
758
745
  return result
759
746
 
747
+ @field_validator("extra_javascript", mode="before")
748
+ @classmethod
749
+ def validate_extra_javascript(
750
+ cls, values: list[dict[str, Any] | str]
751
+ ) -> list[ExtraJavascript | str]:
752
+ items: list[ExtraJavascript | str] = []
753
+ for value in values:
754
+ if isinstance(value, str):
755
+ if value.endswith(".mjs"):
756
+ item = ExtraJavascript(path=value, type="module")
757
+ items.append(item)
758
+ continue
759
+ items.append(value)
760
+ continue
761
+ item = ExtraJavascript(**value)
762
+ items.append(item)
763
+ return items
764
+
760
765
  @field_validator("dev_addr", mode="before")
761
766
  @classmethod
762
767
  def validate_ip_port(cls, v: str) -> str:
@@ -771,15 +776,51 @@ class AppConfig(BaseModel):
771
776
  raise ValueError(msg)
772
777
  return v
773
778
 
779
+ def get_builder(self) -> Callable[..., Any]:
780
+ build_fn = classhelpers.to_callable(self.build_fn)
781
+ build_kwargs = self.build_fn_arguments or {}
782
+ return functools.partial(build_fn, **build_kwargs)
783
+
784
+ def set_theme(
785
+ self,
786
+ theme: str | dict[str, Any] | themeconfig.ThemeConfig,
787
+ **kwargs: Any,
788
+ ):
789
+ match theme:
790
+ case themeconfig.ThemeConfig():
791
+ self.theme = theme
792
+ case dict():
793
+ self.theme = themeconfig.ThemeConfig(**{**theme, **kwargs})
794
+ case str():
795
+ self.theme = themeconfig.ThemeConfig(name=theme, **kwargs)
796
+
797
+ def remove_plugin(self, name: str):
798
+ for plg in self.plugins:
799
+ if plg == name or (isinstance(plg, dict) and next(iter(plg.keys())) == name):
800
+ self.plugins.remove(plg)
801
+
802
+ # @field_validator("theme", mode="before")
803
+ # @classmethod
804
+ # def validate_theme(cls, value: Any) -> ThemeConfig:
805
+ # if isinstance(value, dict):
806
+ # return themeconfig.ThemeConfig(**value)
807
+ # if isinstance(value, themeconfig.ThemeConfig):
808
+ # return value
809
+ # raise ValueError("Address must be either a dict or Address instance")
774
810
 
775
- if __name__ == "__main__":
776
- import pathlib
777
811
 
812
+ if __name__ == "__main__":
778
813
  import devtools
779
- import yaml
780
-
781
- text = pathlib.Path("mkdocs.yml").read_text("utf-8")
782
- cfg = yaml.unsafe_load(text)
783
- config = AppConfig(**cfg)
784
814
 
785
- devtools.debug(config)
815
+ tests = [
816
+ "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/mkdocs.yml",
817
+ # "https://raw.githubusercontent.com/fastapi-users/fastapi-users/master/mkdocs.yml",
818
+ # "https://raw.githubusercontent.com/pydantic/pydantic/main/mkdocs.yml",
819
+ # "https://raw.githubusercontent.com/facelessuser/pymdown-extensions/refs/heads/main/mkdocs.yml",
820
+ ]
821
+ for url in tests:
822
+ config = AppConfig.from_yaml_file(url)
823
+ config.theme = dict(name="xyz", override_dir="overrides")
824
+
825
+ devtools.debug(config.theme)
826
+ print(config.theme, type(config.theme))
@@ -0,0 +1,64 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from typing import Any, Self
5
+
6
+ from pydantic import BaseModel, Field
7
+ import yamling
8
+
9
+
10
+ class ConfigFile(BaseModel):
11
+ """Base class for config files.
12
+
13
+ A class for loading and managing configuration files in YAML format.
14
+ Supports inheritance between config files and provides methods for
15
+ loading from files or YAML text.
16
+ """
17
+
18
+ config_file_path: str | None = Field(None, exclude=True)
19
+ # Either exclude here or add inherit field to MkNodesConfig?
20
+ inherit: str | None = Field(None, exclude=True, alias="INHERIT")
21
+ """Define the parent for a configuration file.
22
+
23
+ The path must be relative to the location of the primary file.
24
+ """
25
+
26
+ @classmethod
27
+ def from_yaml_file(cls, yaml_path: str | os.PathLike[str], **overrides: Any) -> Self:
28
+ """Create a ConfigFile instance from a YAML file.
29
+
30
+ Args:
31
+ yaml_path: Path to the YAML configuration file
32
+ **overrides: Additional key-value pairs to override values from the file
33
+
34
+ Returns:
35
+ A new instance of the ConfigFile class initialized with the YAML data
36
+ """
37
+ cfg = yamling.load_yaml_file(yaml_path)
38
+ vals = {"config_file_path": str(yaml_path), **cfg, **overrides}
39
+ return cls(**vals)
40
+
41
+ @classmethod
42
+ def from_yaml(cls, text: yamling.YAMLInput, **overrides: Any) -> Self:
43
+ """Create a ConfigFile instance from YAML text.
44
+
45
+ Args:
46
+ text: YAML content as text or file-like object
47
+ **overrides: Additional key-value pairs to override values from the YAML
48
+
49
+ Returns:
50
+ A new instance of the ConfigFile class initialized with the YAML data
51
+ """
52
+ cfg = yamling.load_yaml(text, resolve_inherit=True)
53
+ path = {"config_file_path": str(text.name)} if getattr(text, "name", None) else {} # type: ignore
54
+ vals = {**path, **cfg, **overrides}
55
+ return cls(**vals)
56
+
57
+ def to_yaml(self) -> str:
58
+ """Convert the configuration to YAML format.
59
+
60
+ Returns:
61
+ A string containing the YAML representation of the configuration
62
+ """
63
+ cfg = self.model_dump()
64
+ return yamling.dump_yaml(cfg)