Merge Insiders features

Author: squidfunk

Dockerfile

@@ -33,9 +33,9 @@ WORKDIR /tmp
 # Copy files necessary for build
 COPY material material
 COPY package.json package.json
+COPY pyproject.toml pyproject.toml
 COPY README.md README.md
 COPY *requirements.txt ./
-COPY pyproject.toml pyproject.toml
 
 # Perform build and cleanup artifacts and caches
 RUN \
@@ -48,6 +48,7 @@ RUN \
  git-fast-import \
  jpeg-dev \
  openssh \
+ pngquant \
  tini \
  zlib-dev \
 && \
@@ -64,6 +65,7 @@ RUN \
  if [ "${WITH_PLUGINS}" = "true" ]; then \
  pip install --no-cache-dir \
  mkdocs-material[recommended] \
+ mkdocs-material[git] \
  mkdocs-material[imaging]; \
  fi \
 && \

giscus.json

@@ -79,6 +79,7 @@ Issues = "https://github.com/squidfunk/mkdocs-material/issues"
 "material/info" = "material.plugins.info.plugin:InfoPlugin"
 "material/meta" = "material.plugins.meta.plugin:MetaPlugin"
 "material/offline" = "material.plugins.offline.plugin:OfflinePlugin"
+"material/optimize" = "material.plugins.optimize.plugin:OptimizePlugin"
 "material/privacy" = "material.plugins.privacy.plugin:PrivacyPlugin"
 "material/search" = "material.plugins.search.plugin:SearchPlugin"
 "material/social" = "material.plugins.social.plugin:SocialPlugin"

pyproject.toml

@@ -0,0 +1,223 @@
+# Copyright (c) 2016-2025 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import logging
+
+from material.utilities.filter import FileFilter, FilterConfig
+from mkdocs.structure.pages import _RelativePathTreeprocessor
+from markdown import Extension, Markdown
+from markdown.treeprocessors import Treeprocessor
+from mkdocs.exceptions import ConfigurationError
+from urllib.parse import urlparse
+from xml.etree.ElementTree import Element
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+class PreviewProcessor(Treeprocessor):
+ """
+ A Markdown treeprocessor to enable instant previews on links.
+
+ Note that this treeprocessor is dependent on the `relpath` treeprocessor
+ registered programmatically by MkDocs before rendering a page.
+ """
+
+ def __init__(self, md: Markdown, config: dict):
+ """
+ Initialize the treeprocessor.
+
+ Arguments:
+ md: The Markdown instance.
+ config: The configuration.
+ """
+ super().__init__(md)
+ self.config = config
+
+ def run(self, root: Element):
+ """
+ Run the treeprocessor.
+
+ Arguments:
+ root: The root element of the parsed Markdown document.
+ """
+ at = self.md.treeprocessors.get_index_for_name("relpath")
+
+ # Hack: Python Markdown has no notion of where it is, i.e., which file
+ # is being processed. This seems to be a deliberate design decision, as
+ # it is not possible to access the file path of the current page, but
+ # it might also be an oversight that is now impossible to fix. However,
+ # since this extension is only useful in the context of Material for
+ # MkDocs, we can assume that the _RelativePathTreeprocessor is always
+ # present, telling us the file path of the current page. If that ever
+ # changes, we would need to wrap this extension in a plugin, but for
+ # the time being we are sneaky and will probably get away with it.
+ processor = self.md.treeprocessors[at]
+ if not isinstance(processor, _RelativePathTreeprocessor):
+ raise TypeError("Relative path processor not registered")
+
+ # Normalize configurations
+ configurations = self.config["configurations"]
+ configurations.append({
+ "sources": self.config.get("sources"),
+ "targets": self.config.get("targets")
+ })
+
+ # Walk through all configurations - @todo refactor so that we don't
+ # iterate multiple times over the same elements
+ for configuration in configurations:
+
+ # Skip, if the configuration defines nothing – we could also fix
+ # this in the file filter, but we first fix it here and check if
+ # it generalizes well enough to other inclusion/exclusion sites,
+ # because here, it would hinder the ability to automaticaly
+ # include all sources, while excluding specific targets.
+ if (
+ not configuration.get("sources") and
+ not configuration.get("targets")
+ ):
+ continue
+
+ # Skip if page should not be considered
+ filter = get_filter(configuration, "sources")
+ if not filter(processor.file):
+ continue
+
+ # Walk through all links and add preview attributes
+ filter = get_filter(configuration, "targets")
+ for el in root.iter("a"):
+ href = el.get("href")
+ if not href:
+ continue
+
+ # Skip footnotes
+ if "footnote-ref" in el.get("class", ""):
+ continue
+
+ # Skip external links
+ url = urlparse(href)
+ if url.scheme or url.netloc:
+ continue
+
+ # Add preview attribute to internal links
+ for path in processor._possible_target_uris(
+ processor.file, url.path,
+ processor.config.use_directory_urls
+ ):
+ target = processor.files.get_file_from_path(path)
+ if not target:
+ continue
+
+ # Include, if filter matches
+ if filter(target):
+ el.set("data-preview", "")
+
+# -----------------------------------------------------------------------------
+
+class PreviewExtension(Extension):
+ """
+ A Markdown extension to enable instant previews on links.
+
+ This extensions allows to automatically add the `data-preview` attribute to
+ internal links matching specific criteria, so Material for MkDocs renders a
+ nice preview on hover as part of a tooltip. It is the recommended way to
+ add previews to links in a programmatic way.
+ """
+
+ def __init__(self, *args, **kwargs):
+ """
+ """
+ self.config = {
+ "configurations": [[], "Filter configurations"],
+ "sources": [{}, "Link sources"],
+ "targets": [{}, "Link targets"]
+ }
+ super().__init__(*args, **kwargs)
+
+ def extendMarkdown(self, md: Markdown):
+ """
+ Register Markdown extension.
+
+ Arguments:
+ md: The Markdown instance.
+ """
+ md.registerExtension(self)
+
+ # Create and register treeprocessor - we use the same priority as the
+ # `relpath` treeprocessor, the latter of which is guaranteed to run
+ # after our treeprocessor, so we can check the original Markdown URIs
+ # before they are resolved to URLs.
+ processor = PreviewProcessor(md, self.getConfigs())
+ md.treeprocessors.register(processor, "preview", 0)
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+def get_filter(settings: dict, key: str):
+ """
+ Get file filter from settings.
+
+ Arguments:
+ settings: The settings.
+ key: The key in the settings.
+
+ Returns:
+ The file filter.
+ """
+ config = FilterConfig()
+ config.load_dict(settings.get(key) or {})
+
+ # Validate filter configuration
+ errors, warnings = config.validate()
+ for _, w in warnings:
+ log.warning(
+ f"Error reading filter configuration in '{key}':\n"
+ f"{w}"
+ )
+ for _, e in errors:
+ raise ConfigurationError(
+ f"Error reading filter configuration in '{key}':\n"
+ f"{e}"
+ )
+
+ # Return file filter
+ return FileFilter(config = config) # type: ignore
+
+def makeExtension(**kwargs):
+ """
+ Register Markdown extension.
+
+ Arguments:
+ **kwargs: Configuration options.
+
+ Returns:
+ The Markdown extension.
+ """
+ return PreviewExtension(**kwargs)
+
+# -----------------------------------------------------------------------------
+# Data
+# -----------------------------------------------------------------------------
+
+# Set up logging
+log = logging.getLogger("mkdocs.material.extensions.preview")

src/extensions/preview.py

@@ -17,3 +17,17 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
+
+from .structure import View
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+# Sort views by name
+def view_name(view: View):
+ return view.name
+
+# Sort views by post count
+def view_post_count(view: View):
+ return len(view.posts)

src/plugins/blog/__init__.py

@@ -23,6 +23,8 @@
 from mkdocs.config.base import Config
 from pymdownx.slugs import slugify
 
+from . import view_name
+
 # -----------------------------------------------------------------------------
 # Classes
 # -----------------------------------------------------------------------------
@@ -56,6 +58,8 @@ class BlogConfig(Config):
  archive_date_format = Type(str, default = "yyyy")
  archive_url_date_format = Type(str, default = "yyyy")
  archive_url_format = Type(str, default = "archive/{date}")
+ archive_pagination = Optional(Type(bool))
+ archive_pagination_per_page = Optional(Type(int))
  archive_toc = Optional(Type(bool))
 
  # Settings for categories
@@ -64,12 +68,22 @@ class BlogConfig(Config):
  categories_url_format = Type(str, default = "category/{slug}")
  categories_slugify = Type(Callable, default = slugify(case = "lower"))
  categories_slugify_separator = Type(str, default = "-")
+ categories_sort_by = Type(Callable, default = view_name)
+ categories_sort_reverse = Type(bool, default = False)
  categories_allowed = Type(list, default = [])
+ categories_pagination = Optional(Type(bool))
+ categories_pagination_per_page = Optional(Type(int))
  categories_toc = Optional(Type(bool))
 
  # Settings for authors
  authors = Type(bool, default = True)
  authors_file = Type(str, default = "{blog}/.authors.yml")
+ authors_profiles = Type(bool, default = False)
+ authors_profiles_name = Type(str, default = "blog.authors")
+ authors_profiles_url_format = Type(str, default = "author/{slug}")
+ authors_profiles_pagination = Optional(Type(bool))
+ authors_profiles_pagination_per_page = Optional(Type(int))
+ authors_profiles_toc = Optional(Type(bool))
 
  # Settings for pagination
  pagination = Type(bool, default = True)