From dfdc5691c44779cc4d4bc4bf2ba693022b4914d7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 12 Feb 2026 16:53:32 +0000 Subject: [PATCH] Loaders configuration --- docs/configuration.md | 84 ------------------- docs/index.md | 16 ++-- docs/styling.md | 29 +++---- mkdocs.toml | 8 +- .../css/highlightjs-copy.min.css | 0 .../css/highlightjs.min.css | 0 src/mkdocs/{theme => default}/css/theme.css | 0 .../js/highlightjs-copy.min.js | 0 .../{theme => default}/js/highlightjs.min.js | 0 src/mkdocs/{theme => default}/js/theme.js | 0 .../{theme => default}/templates/base.html | 0 src/mkdocs/mkdocs.py | 63 +++++++------- 12 files changed, 55 insertions(+), 145 deletions(-) delete mode 100644 docs/configuration.md rename src/mkdocs/{theme => default}/css/highlightjs-copy.min.css (100%) rename src/mkdocs/{theme => default}/css/highlightjs.min.css (100%) rename src/mkdocs/{theme => default}/css/theme.css (100%) rename src/mkdocs/{theme => default}/js/highlightjs-copy.min.js (100%) rename src/mkdocs/{theme => default}/js/highlightjs.min.js (100%) rename src/mkdocs/{theme => default}/js/theme.js (100%) rename src/mkdocs/{theme => default}/templates/base.html (100%) diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index c67024c..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,84 +0,0 @@ -# Configuration - -Site navigation and other configuration is defined in a `mkdocs.toml` file. - -```toml -[mkdocs] -nav = [ - {title="Introduction", path="index.md"}, - {title="Writing Markdown", path="writing.md"}, - {title="Site Navigation", path="navigation.md"}, - {title="HTML Styling", path="styling.md"} -] -``` - -Navigation can include subsections... - -```toml -[mkdocs] -nav = [ - {title="Introduction", path="README.md"}, - {title="Guides", children=[ - {title="Writing Markdown", path="writing.md"}, - {title="Site Navigation", path="navigation.md"}, - {title="HTML Styling", path="styling.md"} - ]} -] -``` - -### Loaders - -Loaders determine where documentation resources are collected from. - -```toml -loaders = [ - {type="directory", dir="docs"}, - {type="package", pkg="mkdocs.theme"} -] -``` - -Customise this to load a different theme, from a ZIP archive... - -```toml -loaders = [ - {type="directory", dir="docs"}, - {type="url", url="https://www.example.com/theme.zip"} -] -``` - -Or from a GitHub repo... - -```toml -loaders = [ - {type="directory", dir="docs"}, - {type="github", url="mkdocs/default"} -] -``` - - \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 7ebf14e..bc8f4b4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -35,10 +35,14 @@ nav = [ {path: "README.md", title: "Introduction"}, {path: "CREDITS.md", title: "Credits"}, ] -loaders = [ - {package: "mkdocs:theme"}, - {directory: "docs"}, -] + +[loaders] +theme = "pkg://mkdocs/default" +docs = "dir://docs" + +[context] +title = "Documentation" +favicon = "📘" ``` *Use either [`README.md` or `index.md`](navigation.md#url-structure) for the homepage.* @@ -49,7 +53,3 @@ Styling adaptations can be kept simple, such as customising the colour scheme, o 1. Modify [the HTML templating](styling.md#templates) to customise the layout. 2. Override or add [CSS and JavaScript](styling.md#statics) static assets. - -## Compatibility - -*Work is planned to handle compatibility for both [mkdocs 2.x](https://www.encode.io/mkdocs/) sites, and [mkdocs 1.x](https://www.mkdocs.org/) sites.* diff --git a/docs/styling.md b/docs/styling.md index bd5536d..513220b 100644 --- a/docs/styling.md +++ b/docs/styling.md @@ -121,40 +121,33 @@ Controlling how resources are loaded for the theme and documentation is handled *The default theme supplied by the `mkdocs` package, and the documentation served directly from the project directory. This is the default configuration...* ```toml -[mkdocs] -resources = [ - {package="mkdocs:theme"}, - {directory="."}, -] +[loaders] +theme = "pkg://mkdocs/default" +docs = "dir://" ``` *The default theme as a `.zip` URL, and a local `docs` directory...* ```toml -[mkdocs] -resources = [ - {url="https://github.com/lovelydinosaur/mkdocs-theme/archive/refs/heads/main.zip"}, - {directory="docs"}, -] +[loaders] +theme = "https://github.com/lovelydinosaur/mkdocs-theme/archive/refs/heads/main.zip" +docs = "dir://docs" ``` *A theme downloaded locally, and a `docs` directory...* ```toml -[mkdocs] -resources = [ - {directory="theme"}, - {directory="docs"}, -] +[loaders] +theme = "dir://theme" +docs = "dir://docs" ``` *Both the theme and the documentation included in a single directory...* ```toml [mkdocs] -resources = [ - {directory="docs"}, -] +theme = "dir://docs" +docs = "dir://docs" ```
diff --git a/mkdocs.toml b/mkdocs.toml index ce05255..dfe535a 100644 --- a/mkdocs.toml +++ b/mkdocs.toml @@ -5,10 +5,10 @@ nav = [ {title="Interlinking & Navigation", path="navigation.md"}, {title="Themes & Styling", path="styling.md"} ] -resources = [ - {package="mkdocs:theme"}, - {directory="docs"}, -] + +[loaders] +theme = "pkg://mkdocs/default" +docs = "dir://docs" [context] title = "MkDocs" diff --git a/src/mkdocs/theme/css/highlightjs-copy.min.css b/src/mkdocs/default/css/highlightjs-copy.min.css similarity index 100% rename from src/mkdocs/theme/css/highlightjs-copy.min.css rename to src/mkdocs/default/css/highlightjs-copy.min.css diff --git a/src/mkdocs/theme/css/highlightjs.min.css b/src/mkdocs/default/css/highlightjs.min.css similarity index 100% rename from src/mkdocs/theme/css/highlightjs.min.css rename to src/mkdocs/default/css/highlightjs.min.css diff --git a/src/mkdocs/theme/css/theme.css b/src/mkdocs/default/css/theme.css similarity index 100% rename from src/mkdocs/theme/css/theme.css rename to src/mkdocs/default/css/theme.css diff --git a/src/mkdocs/theme/js/highlightjs-copy.min.js b/src/mkdocs/default/js/highlightjs-copy.min.js similarity index 100% rename from src/mkdocs/theme/js/highlightjs-copy.min.js rename to src/mkdocs/default/js/highlightjs-copy.min.js diff --git a/src/mkdocs/theme/js/highlightjs.min.js b/src/mkdocs/default/js/highlightjs.min.js similarity index 100% rename from src/mkdocs/theme/js/highlightjs.min.js rename to src/mkdocs/default/js/highlightjs.min.js diff --git a/src/mkdocs/theme/js/theme.js b/src/mkdocs/default/js/theme.js similarity index 100% rename from src/mkdocs/theme/js/theme.js rename to src/mkdocs/default/js/theme.js diff --git a/src/mkdocs/theme/templates/base.html b/src/mkdocs/default/templates/base.html similarity index 100% rename from src/mkdocs/theme/templates/base.html rename to src/mkdocs/default/templates/base.html diff --git a/src/mkdocs/mkdocs.py b/src/mkdocs/mkdocs.py index 619506b..3629321 100644 --- a/src/mkdocs/mkdocs.py +++ b/src/mkdocs/mkdocs.py @@ -1,6 +1,7 @@ import base64 import io import json +import os import pathlib import posixpath import typing @@ -13,6 +14,7 @@ import tomllib import importlib.resources +from urllib.parse import urlparse from .extensions.rewrite_urls import PageContext @@ -85,9 +87,11 @@ class Directory(Handler): A handler for loading resources from the local filesystem. """ - def __init__(self, dir: pathlib.Path | None = None) -> None: - self._dir = pathlib.Path.cwd() if dir is None else pathlib.Path(dir) - self._dir_repr = '[CWD]' if dir is None else f"{dir!r}" + def __init__(self, url: str = 'dir://') -> None: + parsed = urlparse(url) + dir = parsed.netloc + parsed.path + self._dir = pathlib.Path(dir.lstrip('/')) if dir else pathlib.Path.cwd() + self._dir_repr = f"{dir!r}" if dir else '[CWD]' def load_paths(self) -> list[pathlib.Path]: return sorted([ @@ -108,8 +112,9 @@ class Package(Handler): A handler for loading resources from a python package. """ - def __init__(self, pkg_dir: str = 'mkdocs:theme') -> None: - pkg, _, dir = pkg_dir.partition(':') + def __init__(self, url: str = 'pkg://mkdocs/default') -> None: + parsed = urlparse(url) + pkg, dir = parsed.netloc, parsed.path.lstrip('/') self._files = importlib.resources.files(pkg).joinpath(dir) def _load_paths(self, subdir: str) -> list[pathlib.Path]: @@ -135,7 +140,7 @@ def __repr__(self): class ZipURL(Handler): - def __init__(self, url: str) -> None: + def __init__(self, url: str = "https://") -> None: self._url = url self._topdir = '' @@ -244,6 +249,11 @@ def get_source(self, environment: jinja2.Environment, template: str): class MkDocs: def __init__(self): + self.loaders = { + 'https': ZipURL, + 'pkg': Package, + 'dir': Directory, + } self.config = self.load_config('mkdocs.toml') self.handlers = self.load_handlers(self.config) self.resources, self.templates = self.load_resources(self.handlers) @@ -282,10 +292,10 @@ def load_config(self, filename: str) -> dict: default = { 'mkdocs': { 'nav': [], - 'resources': [ - {'package': 'mkdocs:theme'}, - {'directory': 'docs'}, - ], + }, + 'loaders': { + 'theme': 'pkg://mkdocs/default', + 'docs': 'dir://', }, 'context': { }, @@ -313,27 +323,18 @@ def load_config(self, filename: str) -> dict: return Config(config, filename=filename) def load_handlers(self, config: dict) -> list[Handler]: - handlers = [] - for handler in config['mkdocs']['resources']: - if len(handler) != 1: - raise ConfigError("Misconfigured 'resources' section.") - key = list(handler.keys())[0] - value = list(handler.values())[0] - if key == 'url': - handlers.append(ZipURL(value)) - elif key == 'package': - handlers.append(Package(value)) - elif key == 'directory': - handlers.append(Directory(value)) - return handlers - - # return [ - # # ZipURL('https://codeload.github.com/lovelydinosaur/test/zip/refs/tags/v2'), - # ZipURL('https://codeload.github.com/lovelydinosaur/test/zip/refs/heads/main'), - # # Package('mkdocs'), - # # ZipURL('https://github.com/lovelydinosaur/test/archive/refs/heads/main.zip'), - # Directory('docs'), - # ] + loaders_config = config['loaders'] + + theme_url = loaders_config['theme'] + docs_url = loaders_config['docs'] + + urls = [docs_url] if theme_url == docs_url else [theme_url, docs_url] + loaders = [] + for url in urls: + scheme = urlparse(url).scheme + cls = self.loaders[scheme] + loaders.append(cls(url)) + return loaders def load_resources(self, handlers: list[Handler]) -> tuple[list[Resource], list[Template]]: resources = {}