Merged features tied to 'Chipotle' funding goal

Author: squidfunk

material/plugins/blog/plugin.py

@@ -26,6 +26,7 @@
 import yaml
 
 from babel.dates import format_date, format_datetime
+from copy import copy
 from datetime import datetime, timezone
 from jinja2 import pass_context
 from jinja2.runtime import Context
@@ -34,19 +35,20 @@
 from mkdocs.plugins import BasePlugin, event_priority
 from mkdocs.structure import StructureItem
 from mkdocs.structure.files import File, Files, InclusionLevel
-from mkdocs.structure.nav import Navigation, Section
+from mkdocs.structure.nav import Link, Navigation, Section
 from mkdocs.structure.pages import Page
+from mkdocs.structure.toc import AnchorLink, TableOfContents
 from mkdocs.utils import copy_file, get_relative_url
-from mkdocs.utils.templates import url_filter
 from paginate import Page as Pagination
 from shutil import rmtree
 from tempfile import mkdtemp
+from urllib.parse import urlparse
 from yaml import SafeLoader
 
 from .author import Authors
 from .config import BlogConfig
 from .readtime import readtime
-from .structure import Archive, Category, Excerpt, Post, View
+from .structure import Archive, Category, Excerpt, Post, Reference, View
 
 # -----------------------------------------------------------------------------
 # Classes
@@ -299,10 +301,18 @@ def on_env(self, env, *, config, files):
         if not self.config.enabled:
             return
 
+        # Transform links to point to posts and pages
+        for post in self.blog.posts:
+            self._generate_links(post, config, files)
+
         # Filter for formatting dates related to posts
         def date_filter(date: datetime):
             return self._format_date_for_post(date, config)
 
+        # Fetch URL template filter from environment - the filter might
+        # be overridden by other plugins, so we must retrieve and wrap it
+        url_filter = env.filters["url"]
+
         # Patch URL template filter to add support for paginated views, i.e.,
         # that paginated views never link to themselves but to the main view
         @pass_context
@@ -524,14 +534,15 @@ def _generate_archive(self, config: MkDocsConfig, files: Files):
 
             # Create file for view, if it does not exist
             file = files.get_file_from_path(path)
-            if not file or self.temp_dir not in file.abs_src_path:
+            if not file:
                 file = self._path_to_file(path, config)
                 files.append(file)
 
-                # Create file in temporary directory and temporarily remove
-                # from navigation, as we'll add it at a specific location
+                # Create file in temporary directory
                 self._save_to_file(file.abs_src_path, f"# {name}")
-                file.inclusion = InclusionLevel.EXCLUDED
+
+            # Temporarily remove view from navigation
+            file.inclusion = InclusionLevel.EXCLUDED
 
             # Create and yield view
             if not isinstance(file.page, Archive):
@@ -560,14 +571,15 @@ def _generate_categories(self, config: MkDocsConfig, files: Files):
 
                 # Create file for view, if it does not exist
                 file = files.get_file_from_path(path)
-                if not file or self.temp_dir not in file.abs_src_path:
+                if not file:
                     file = self._path_to_file(path, config)
                     files.append(file)
 
-                    # Create file in temporary directory and temporarily remove
-                    # from navigation, as we'll add it at a specific location
+                    # Create file in temporary directory
                     self._save_to_file(file.abs_src_path, f"# {name}")
-                    file.inclusion = InclusionLevel.EXCLUDED
+
+                # Temporarily remove view from navigation
+                file.inclusion = InclusionLevel.EXCLUDED
 
                 # Create and yield view
                 if not isinstance(file.page, Category):
@@ -591,14 +603,15 @@ def _generate_pages(self, view: View, config: MkDocsConfig, files: Files):
 
             # Create file for view, if it does not exist
             file = files.get_file_from_path(path)
-            if not file or self.temp_dir not in file.abs_src_path:
+            if not file:
                 file = self._path_to_file(path, config)
                 files.append(file)
 
-                # Copy file to temporary directory  and temporarily remove
-                # from navigation, as we'll add it at a specific location
+                # Copy file to temporary directory
                 copy_file(view.file.abs_src_path, file.abs_src_path)
-                file.inclusion = InclusionLevel.EXCLUDED
+
+            # Temporarily remove view from navigation
+            file.inclusion = InclusionLevel.EXCLUDED
 
             # Create and yield view
             if not isinstance(file.page, View):
@@ -609,6 +622,79 @@ def _generate_pages(self, view: View, config: MkDocsConfig, files: Files):
             file.page.pages = view.pages
             file.page.posts = view.posts
 
+    # Generate links from the given post to other posts, pages, and sections -
+    # this can only be done once all posts and pages have been parsed
+    def _generate_links(self, post: Post, config: MkDocsConfig, files: Files):
+        if not post.config.links:
+            return
+
+        # Resolve path relative to docs directory for error reporting
+        docs = os.path.relpath(config.docs_dir)
+        path = os.path.relpath(post.file.abs_src_path, docs)
+
+        # Find all links to pages and replace them with references - while all
+        # internal links are processed, external links remain as they are
+        for link in _find_links(post.config.links.items):
+            url = urlparse(link.url)
+            if url.scheme:
+                continue
+
+            # Resolve file for link, and throw if the file could not be found -
+            # authors can link to other pages, as well as to assets or files of
+            # any kind, but it is essential that the file that is linked to is
+            # found, so errors are actually catched and reported
+            file = files.get_file_from_path(url.path)
+            if not file:
+                log.warning(
+                    f"Error reading metadata of post '{path}' in '{docs}':\n"
+                    f"Couldn't find file for link '{url.path}'"
+                )
+                continue
+
+            # If the file linked to is not a page, but an asset or any other
+            # file, we resolve the destination URL and continue
+            if not isinstance(file.page, Page):
+                link.url = file.url
+                continue
+
+            # Cast link to reference
+            link.__class__ = Reference
+            assert isinstance(link, Reference)
+
+            # Assign page title, URL and metadata to link
+            link.title = link.title or file.page.title
+            link.url   = file.page.url
+            link.meta  = copy(file.page.meta)
+
+            # If the link has no fragment, we can continue - if it does, we
+            # need to find the matching anchor in the table of contents
+            if not url.fragment:
+                continue
+
+            # If we're running under dirty reload, MkDocs will reset all pages,
+            # so it's not possible to resolve anchor links. Thus, the only way
+            # to make this work is to skip the entire process of anchor link
+            # resolution in case of a dirty reload.
+            if self.is_dirty:
+                continue
+
+            # Resolve anchor for fragment, and throw if the anchor could not be
+            # found - authors can link to any anchor in the table of contents
+            anchor = _find_anchor(file.page.toc, url.fragment)
+            if not anchor:
+                log.warning(
+                    f"Error reading metadata of post '{path}' in '{docs}':\n"
+                    f"Couldn't find anchor '{url.fragment}' in '{url.path}'"
+                )
+
+                # Restore link to original state
+                link.url = url.geturl()
+                continue
+
+            # Append anchor to URL and set subtitle
+            link.url += f"#{anchor.id}"
+            link.meta["subtitle"] = anchor.title
+
     # -------------------------------------------------------------------------
 
     # Attach a list of pages to each other and to the given parent item without
@@ -864,6 +950,35 @@ def _translate(self, key: str, config: MkDocsConfig) -> str:
         # Translate placeholder
         return template.module.t(key)
 
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+# Find all links in the given list of items
+def _find_links(items: list[StructureItem]):
+    for item in items:
+
+        # Resolve link
+        if isinstance(item, Link):
+            yield item
+
+        # Resolve sections recursively
+        if isinstance(item, Section):
+            for item in _find_links(item.children):
+                assert isinstance(item, Link)
+                yield item
+
+# Find anchor in table of contents for the given id
+def _find_anchor(toc: TableOfContents, id: str):
+    for anchor in toc:
+        if anchor.id == id:
+            return anchor
+
+        # Resolve anchors recursively
+        anchor = _find_anchor(anchor.children, id)
+        if isinstance(anchor, AnchorLink):
+            return anchor
+
 # -----------------------------------------------------------------------------
 # Data
 # -----------------------------------------------------------------------------

material/plugins/blog/structure/__init__.py

@@ -27,10 +27,11 @@
 from copy import copy
 from markdown import Markdown
 from material.plugins.blog.author import Author
+from material.plugins.meta.plugin import MetaPlugin
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.exceptions import PluginError
 from mkdocs.structure.files import File, Files
-from mkdocs.structure.nav import Section
+from mkdocs.structure.nav import Link, Section
 from mkdocs.structure.pages import Page, _RelativePathTreeprocessor
 from mkdocs.structure.toc import get_toc
 from mkdocs.utils.meta import YAML_RE
@@ -87,6 +88,19 @@ def __init__(self, file: File, config: MkDocsConfig):
                     f"{e}"
                 )
 
+            # Hack: if the meta plugin is registered, we need to move the call
+            # to `on_page_markdown` here, because we need to merge the metadata
+            # of the post with the metadata of any meta files prior to creating
+            # the post configuration. To our current knowledge, it's the only
+            # way to allow posts to receive metadata from meta files, because
+            # posts must be loaded prior to constructing the navigation in
+            # `on_files` but the meta plugin first runs in `on_page_markdown`.
+            plugin: MetaPlugin = config.plugins.get("material/meta")
+            if plugin:
+                plugin.on_page_markdown(
+                    self.markdown, page = self, config = config, files = None
+                )
+
         # Initialize post configuration, but remove all keys that this plugin
         # doesn't care about, or they will be reported as invalid configuration
         self.config: PostConfig = PostConfig(file.abs_src_path)
@@ -257,6 +271,17 @@ class Archive(View):
 class Category(View):
     pass
 
+# -----------------------------------------------------------------------------
+
+# Reference
+class Reference(Link):
+
+    # Initialize reference - this is essentially a crossover of pages and links,
+    # as it inherits the metadata of the page and allows for anchors
+    def __init__(self, title: str, url: str):
+        super().__init__(title, url)
+        self.meta = {}
+
 # -----------------------------------------------------------------------------
 # Helper functions
 # -----------------------------------------------------------------------------

material/plugins/blog/structure/config.py

@@ -19,19 +19,20 @@
 # IN THE SOFTWARE.
 
 from mkdocs.config.base import Config
-from mkdocs.config.config_options import ListOfItems, Optional, Type
+from mkdocs.config.config_options import Optional, Type
 
-from .options import PostDate
+from .options import PostDate, PostLinks, UniqueListOfItems
 
 # -----------------------------------------------------------------------------
 # Classes
 # -----------------------------------------------------------------------------
 
 # Post configuration
 class PostConfig(Config):
-    authors = ListOfItems(Type(str), default = [])
-    categories = ListOfItems(Type(str), default = [])
+    authors = UniqueListOfItems(Type(str), default = [])
+    categories = UniqueListOfItems(Type(str), default = [])
     date = PostDate()
     draft = Optional(Type(bool))
+    links = Optional(PostLinks())
     readtime = Optional(Type(int))
     slug = Optional(Type(str))

material/plugins/blog/structure/markdown.py

@@ -18,6 +18,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+from __future__ import annotations
+
 from markdown.treeprocessors import Treeprocessor
 from mkdocs.structure.pages import Page
 from mkdocs.utils import get_relative_url
@@ -31,12 +33,13 @@
 class ExcerptTreeprocessor(Treeprocessor):
 
     # Initialize excerpt tree processor
-    def __init__(self, page: Page, base: Page = None):
+    def __init__(self, page: Page, base: Page | None = None):
         self.page = page
         self.base = base
 
     # Transform HTML after Markdown processing
     def run(self, root: Element):
+        assert self.base
         main = True
 
         # We're only interested in anchors, which is why we continue when the

material/plugins/blog/structure/options.py

@@ -20,6 +20,11 @@
 
 from datetime import date, datetime, time, timezone
 from mkdocs.config.base import BaseConfigOption, Config, ValidationError
+from mkdocs.config.config_options import ListOfItems, T
+from mkdocs.structure.files import Files
+from mkdocs.structure.nav import (
+    Navigation, _add_parent_links, _data_to_navigation
+)
 from typing import Dict
 
 # -----------------------------------------------------------------------------
@@ -97,3 +102,27 @@ def run_validation(self, value: DateDict):
 
         # Return date dictionary
         return value
+
+# -----------------------------------------------------------------------------
+
+# Post links option
+class PostLinks(BaseConfigOption[Navigation]):
+
+    # Create navigation from structured items - we don't need to provide a
+    # configuration object to the function, because it will not be used
+    def run_validation(self, value: object):
+        items = _data_to_navigation(value, Files([]), None)
+        _add_parent_links(items)
+
+        # Return navigation
+        return Navigation(items, [])
+
+# -----------------------------------------------------------------------------
+
+# Unique list of items
+class UniqueListOfItems(ListOfItems[T]):
+
+    # Ensure that each item is unique
+    def run_validation(self, value: object):
+        data = super().run_validation(value)
+        return list(dict.fromkeys(data))

material/plugins/meta/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2016-2025 Martin Donath <[email protected]>
+
+# 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.