|
| 1 | +"""MkDocs hooks for the HyperCache site. |
| 2 | +
|
| 3 | +Rewrites repo-relative links to source files (`../pkg/foo.go`, |
| 4 | +`../../hypercache.go`, etc.) into canonical GitHub URLs, so the same |
| 5 | +markdown source renders correctly both on github.com and on the |
| 6 | +GitHub Pages MkDocs build. |
| 7 | +
|
| 8 | +Without this, the operations runbook and the RFCs reference dozens |
| 9 | +of source files via paths like `../pkg/backend/dist_memory.go`. |
| 10 | +GitHub renders those as in-repo links; MkDocs's strict mode flags |
| 11 | +them as broken because `pkg/` is not part of the documentation |
| 12 | +tree. Rewriting them at build time keeps the source markdown |
| 13 | +GitHub-friendly while letting strict mode actually enforce |
| 14 | +docs-internal correctness. |
| 15 | +""" |
| 16 | + |
| 17 | +import os |
| 18 | +import re |
| 19 | +from typing import Any |
| 20 | + |
| 21 | +GITHUB_REPO_BASE = "https://github.com/hyp3rd/hypercache/blob/main" |
| 22 | + |
| 23 | +# File extensions that we treat as "source code, not docs" — links |
| 24 | +# to these get rewritten to GitHub URLs. .md is intentionally NOT |
| 25 | +# in this list because doc-to-doc links should stay intra-site so |
| 26 | +# MkDocs can validate them. |
| 27 | +SOURCE_EXTENSIONS = ( |
| 28 | + ".go", |
| 29 | + ".yaml", |
| 30 | + ".yml", |
| 31 | + ".sh", |
| 32 | + ".rb", |
| 33 | + ".txt", |
| 34 | + ".dockerignore", |
| 35 | + ".gitignore", |
| 36 | + ".env", |
| 37 | + "Dockerfile", |
| 38 | + "Makefile", |
| 39 | +) |
| 40 | + |
| 41 | +# Paths that are entire directories the docs reference for context |
| 42 | +# (e.g. "see internal/cluster/"). These get rewritten to GitHub |
| 43 | +# tree URLs — clicking takes the reader to a directory listing. |
| 44 | +SOURCE_DIR_PREFIXES = ( |
| 45 | + "pkg/", |
| 46 | + "internal/", |
| 47 | + "cmd/", |
| 48 | + "chart/", |
| 49 | + "scripts/", |
| 50 | + "tests/", |
| 51 | + "__examples/", |
| 52 | + ".github/", |
| 53 | + "docker/", |
| 54 | +) |
| 55 | + |
| 56 | +LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)") |
| 57 | + |
| 58 | + |
| 59 | +def _is_source_link(target: str) -> bool: |
| 60 | + """Return True when the link target looks like a repo source ref |
| 61 | + rather than an in-tree docs link.""" |
| 62 | + # Strip anchor before extension/prefix checks. |
| 63 | + clean = target.split("#", 1)[0] |
| 64 | + |
| 65 | + # Source files by extension or basename. |
| 66 | + if clean.endswith(SOURCE_EXTENSIONS): |
| 67 | + return True |
| 68 | + |
| 69 | + # Directory references (no extension) that match known source |
| 70 | + # roots. We resolve `..` segments first so the prefix match |
| 71 | + # works against repo-rooted paths. |
| 72 | + parts = [p for p in clean.split("/") if p and p != "."] |
| 73 | + |
| 74 | + # Drop leading `..` segments — they all collapse to repo root |
| 75 | + # for our purposes (rewrite-target side). |
| 76 | + while parts and parts[0] == "..": |
| 77 | + parts.pop(0) |
| 78 | + |
| 79 | + if not parts: |
| 80 | + return False |
| 81 | + |
| 82 | + repo_path = "/".join(parts) |
| 83 | + if any(repo_path.startswith(p) for p in SOURCE_DIR_PREFIXES): |
| 84 | + return True |
| 85 | + |
| 86 | + return False |
| 87 | + |
| 88 | + |
| 89 | +def _resolve_to_repo_root(page_src_path: str, target: str) -> str: |
| 90 | + """Translate a relative target into a repo-rooted path. |
| 91 | +
|
| 92 | + Page src_path is relative to docs/ (e.g. `rfcs/0001-foo.md`). |
| 93 | + Target is relative to the page (e.g. `../../pkg/foo.go`). The |
| 94 | + returned path is relative to the repo root. |
| 95 | + """ |
| 96 | + # `os.path.normpath` collapses `..` correctly; we anchor at |
| 97 | + # `docs/<page_dir>` and resolve from there. |
| 98 | + page_dir = os.path.dirname(page_src_path) |
| 99 | + docs_anchored = os.path.normpath(os.path.join("docs", page_dir, target)) |
| 100 | + |
| 101 | + # The result may still start with `../` if the relative target |
| 102 | + # walked above the repo root (it shouldn't in practice). Trim |
| 103 | + # any leading `../` defensively. |
| 104 | + while docs_anchored.startswith("../"): |
| 105 | + docs_anchored = docs_anchored[3:] |
| 106 | + |
| 107 | + return docs_anchored |
| 108 | + |
| 109 | + |
| 110 | +def on_page_markdown(markdown: str, page: Any, **kwargs: Any) -> str: |
| 111 | + """Rewrite source-code links on every page before MkDocs renders it.""" |
| 112 | + page_src = page.file.src_path |
| 113 | + |
| 114 | + def replace(match: re.Match[str]) -> str: |
| 115 | + link_text = match.group(1) |
| 116 | + link_target = match.group(2) |
| 117 | + |
| 118 | + # Absolute URLs, mailtos, and pure anchors stay as-is. |
| 119 | + if link_target.startswith(("http://", "https://", "mailto:", "#")): |
| 120 | + return match.group(0) |
| 121 | + |
| 122 | + if not _is_source_link(link_target): |
| 123 | + return match.group(0) |
| 124 | + |
| 125 | + repo_path = _resolve_to_repo_root(page_src, link_target) |
| 126 | + |
| 127 | + # Preserve any anchor on the target (e.g. line ranges like |
| 128 | + # `pkg/foo.go#L34-L58`). |
| 129 | + if "#" in link_target and "#" not in repo_path: |
| 130 | + anchor = "#" + link_target.split("#", 1)[1] |
| 131 | + repo_path += anchor |
| 132 | + |
| 133 | + return f"[{link_text}]({GITHUB_REPO_BASE}/{repo_path})" |
| 134 | + |
| 135 | + return LINK_RE.sub(replace, markdown) |
0 commit comments