Using Snippets with MkDocs hooks

[Enn83]

Hi!
I'm using mkdocs (and mkdocs-material) and I was trying to make a hook that replace all occurences of a string (for example issue#\d+) by an auto-link to a specific URL (issue#23456 become <a href="...">#23456</a>), it was working well until I noticed that pages included using the snippet notation --8<-- still have the original text (for example issue#12345) instead of the replacement link.

---

For example :

page1.md :

--8<-- "/page2.md"

issue#23456

page2.md :

issue#12345

I got the following result :

page1/ :

issue#12345

<a href="...">#23456</a>

page2/ :

<a href="...">#13245</a>

---

I know It seems logical since I'm including the *.md file in the snippet notation, but is there any way the snippet include the HTML version of the file (so post-hook) ?

I am using the on_page_markdown mkdocs hook because I'm also using some emojis (with syntax :emoji:) so they are converted after by mkdocs into <span class="twemoji">...</span>.
There is also the on_page_content mkdocs hook that will run the hook on the final HTML page (after snippet insert pages with -8<-), but it implies that my hooks directly insert the <span class="twemoji">...</span> instead of short-code emoji, but it can be realy big, make the hook code unreadable and maybe the <span class="twemoji">...</span> won't fit well in the page (mkdocs will do it better than me) 😔, so I prefer to avoid doing this unless there is an easy way to do it.

Thanks in advance 😊 !

[facelessuser]

Keep in mind that Pymdown Extensions is a Python Markdown extension, not a MkDocs extension.

If you are processing the content before Markdown parsing is applied, then you will not have the snippet content passed to MkDocs. During Markdown parsing is when Snippets retrieves the file and inserts it into the Markdown content.

[Enn83]

So I should use the on_page_content mkdocs hook that will run the hook after the final HTML page is build and find out how to insert emojis without the :emoji: notation of mkdocs (or find a trick).

Thanks you!

PS: I will post a reply once I find a way to do this.

[Enn83]

I finally managed to achieve what I wanted, but at a cost (I think the idea is quite ugly, and it could have been better coded, but it's rarely used...).
This allows me to embed documentation pages within other documentation pages to centralize and avoid duplicating information, while still having the option to apply other 🪝hooks to them and then wrote them in markdown:

(Sorry, most of the comments in the hook are in french)

snipp3t hook

# -*- coding: utf-8 -*-
r"""
Hook mkdocs pour insérer le contenu de d'autres fichiers qui pourra ensuite passer par
les autres hooks MkDocs. La syntaxe est similaire au snippet `--8<--` mais avec un `3`
à la place : `---3<------`. Il s'exécute en premier dans les hooks pour permettre aux
suivants de traiter le fichier complet !

Ce snippet permet uniquement d'inclure des fichiers markdown déjà présents dans la
documentation !

Fonctionne comme le snippet `--8<--` mais seulement en mode "une ligne".
Il est possible d'utiliser les sections ou de spécifier les lignes à extraire :

```md title="page1.md" linenums="1" hl_lines="4"
-3<---- "relative/path/to/page2.md:4:9"  # Ligne 4 à 9 (inclus)
--3<--- "relative/path/to/page2.md::21"  # Ligne 0 à 21 (inclus)
---3<-- "relative/path/to/page2.md:5"    # Ligne 5 et +
-3<- "relative/path/to/page2.md:section"
```

Dans le cas où l'on spécifie une section à inclure avec `page2.md:section_name`, il faut
spécifier les sections comme ceci dans le fichier cible (elles peuvent être indentées
mais doivent impérativement être seules sur la ligne !) :
```md title="page2.md"
## Subtitle

=== "Tab1"
    <!-- --3<--[start:section_name] -->
    bla bla bla
    <!-- --3<--[end:section_name] -->

=== "Tab2"
    ...
...
```
"""

from __future__ import annotations

import logging
import os
import re
from re import Match
from textwrap import dedent, indent

from mkdocs import plugins
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import Files
from mkdocs.structure.pages import Page

log = logging.getLogger("mkdocs")
print(
    "\e[38;5;221mSNIPP3T -\e[0m  Loading mkdocs hook 🪝  \e[38;5;221msnipp3t (snippet anticipé)\e[0m."
)


### FONCTION PRINCIPALE ↓↓↓
# https://www.mkdocs.org/dev-guide/plugins/#page-events
@plugins.event_priority(100)
def on_page_markdown(
    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
) -> str:
    """
    Fonction hook appelée par mkdocs-material sur chaque page d'entrée au format MD
    (pré-build) pour replacer des occurences/correspondances du texte d'une page par un
    autre texte avec le snippet `--3<--`.
    """

    # Replace callback
    def replace(match: Match):
        groups = match.groupdict()
        return resolve_snipp3t(groups, page)

    return re.sub(
        r"""(?P<indt>[ \t]*)-+3<-+ ?['"](?P<path>.*?\.md)(?P<qual>:.+?)?['"]""",
        replace,
        markdown,
        flags=re.I | re.M,
    )


def resolve_snipp3t(groups: dict, page: Page) -> str:
    """
    Retourne le contenu du fichier à insérer s'il existe ou la chaîne vide sinon.

    Il est possible de spécifier les lignes à extraire ou bien d'utiliser des balises de
    la même manière que le snippet `--8<--`.

    Parameters:
        groups: Captured group from matched line.
        page: Actual markdown page.

    Returns:
        Replacement text (markdown possible).
    """

    indt: str = groups.get("indt")
    path: str = groups.get("path")
    qual: str = groups.get("qual", None)
    markdown = ""

    def find_anchor(lines, name) -> tuple[int, int]:
        start, end = None, None
        for i in range(len(lines)):
            if re.match(
                r"[ \t]*<!--+ *-+3<-+ *\[start:" + name + r"\] *-+->", lines[i]
            ):
                start = i + 1
            if re.match(r"[ \t]*<!--+ *-+3<-+ *\[end:" + name + r"\] *-+->", lines[i]):
                end = i if i > start else -1
        return start, end

    if os.path.exists(path):
        ### On affiche la substitution (verbose)
        if os.environ.get("HOOK_SNIPP3T_VERBOSE"):
            print(f"\e[36mSNIPP3T -\e[0m  Substitution de '\e[36m{path}\e[0m'.")

        ### Traitement de la substitution
        lines = open(path, "r", encoding="utf-8").readlines()
        start, end = 0, len(lines)
        if qual:  # Intervalle de lignes spécifiques
            if match := re.match(r"^:(\d*)?(?::(\d*))?$", qual):
                # Spécification min:max
                start = max(0, int(match.groups()[0] or start) - 1)
                end = int(match.groups()[1] or end)
                print(start, end)

            elif match := re.match(r"^:([^:]+)$", qual):
                # Spécification d'une section
                s, e = find_anchor(lines, match.groups()[0])
                start = s if s else start
                end = e if s else end

        content = "".join(lines[start:end])

        markdown = indent(dedent(content), indt)

    else:
        ### Fichier introuvable (verbose)
        if os.environ.get("HOOK_SNIPP3T_ALLOW_MISSING"):
            log.warning(f"Substitution '\e[33m{path}\e[0m' introuvable !")
        else:
            log.error(f"Substitution '\e[31m{path}\e[0m' introuvable !")
            raise RuntimeError(f"Substitution '{path}' introuvable !")

    return markdown