docs/main.py at main · pgdogdev/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
import logging
import os
import posixpath
from urllib.parse import urlparse

from mkdocs.structure.files import Files

log = logging.getLogger("mkdocs.plugins.macros")

# Latest released tag for the Enterprise Docker images. Update this in one
# place; reference it in docs with {{ enterprise_tag }}. Can be overridden at
# build time with the ENTERPRISE_TAG environment variable.
ENTERPRISE_TAG = os.environ.get("ENTERPRISE_TAG", "v2026-06-15")


def define_env(env):

    env.variables["enterprise_tag"] = ENTERPRISE_TAG

    def _validate_link(href, page):
        """Check that a .md link target exists on disk."""
        parsed = urlparse(href)
        path = parsed.path

        if not path.endswith(".md") or path.startswith("http"):
            return

        page_dir = posixpath.dirname(page.file.src_path)
        resolved = posixpath.normpath(posixpath.join(page_dir, path))
        abs_path = os.path.join(env.conf["docs_dir"], resolved)

        if not os.path.isfile(abs_path):
            log.warning(
                f"Card link in '{page.file.src_path}' points to "
                f"'{href}' but '{resolved}' does not exist."
            )

    def _resolve_link(href, page):
        """Resolve a relative .md link to the correct site URL."""
        _validate_link(href, page)

        parsed = urlparse(href)
        path = parsed.path

        if not path.endswith(".md") or path.startswith("http"):
            return href

        # Get the directory of the current page source
        page_dir = posixpath.dirname(page.file.src_path)
        # Resolve the relative path
        resolved = posixpath.normpath(posixpath.join(page_dir, path))
        # Convert .md to trailing slash
        resolved = resolved.replace(".md", "/")
        # Handle index files
        if resolved.endswith("/index/"):
            resolved = resolved[: -len("index/")]

        url = "/" + resolved
        if parsed.fragment:
            url += "#" + parsed.fragment
        return url

    @env.macro
    def next_steps_links(links):
        page = env.page
        rendered = []
        for link in links:
            title, href, desc = link
            resolved = _resolve_link(href, page)
            rendered.append(f"""
                <div>
                    <h4><a href="{resolved}">{title}</a></h4>
                    <p>{desc}</p>
                </div>
            """)
        rendered = "\n".join(rendered)
        return f"""<div class="grid">{rendered}</div>"""

    @env.macro
    def card_grid(cards):
        """Render a grid of cards with icon, title, link, and description.
        Each card: (icon, title, link, description)
        """
        page = env.page
        rendered = []
        for card in cards:
            icon, title, href, desc = card
            resolved = _resolve_link(href, page)
            rendered.append(f"""
                <div>
                    <span class="card-icon">{icon}</span>
                    <h4><a href="{resolved}">{title}</a></h4>
                    <p>{desc}</p>
                </div>
            """)
        rendered = "\n".join(rendered)
        return f"""<div class="grid">{rendered}</div>"""