# Copyright (c) 2016-2025 Martin Donath # 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")