Coverage for scripts / mkdocs_hooks.py: 100.00%

1"""MkDocs hook: serve the repository's tracked ``images/`` inside the wiki. 

2 

3Requirement 4.2 of the github-pages-wiki spec forbids wiki pages from using 

4external image hosts (``raw.githubusercontent.com``) *and* from committing 

5duplicate copies of tracked binaries. MkDocs, however, only serves files 

6under ``docs_dir`` (``wiki/``). This hook closes that gap: ``on_files`` 

7injects every file under the repo's ``images/`` directory into the build as 

8``assets/images/<name>``, so wiki pages reference ``assets/images/x.png``, 

9strict link validation sees a real file, and the screenshots stay 

10single-source (regenerating a screenshot updates the wiki automatically). 

11 

12Wired via the ``hooks:`` key in ``mkdocs.yml``. The ``assets/images/`` → 

13``images/`` mapping is mirrored by ``tests/test_wiki.py``, which asserts 

14every image referenced by a wiki page exists in ``images/``. 

15""" 

16 

17from __future__ import annotations 

18 

19from pathlib import Path 

20 

21from mkdocs.config.defaults import MkDocsConfig 

22from mkdocs.structure.files import File, Files 

23 

24#: Repository root (this file lives in ``scripts/``). 

25_REPO_ROOT = Path(__file__).resolve().parent.parent 

26 

27#: Source directory of tracked images and its path prefix inside the site. 

28_IMAGES_DIR = _REPO_ROOT / "images" 

29_SITE_PREFIX = "assets/images" 

30 

31 

32def on_files(files: Files, config: MkDocsConfig) -> Files: 

33 """Inject every tracked image as ``assets/images/<name>``. 

34 

35 ``File.generated`` (MkDocs >= 1.6) registers a file that lives outside 

36 ``docs_dir``; passing ``abs_src_path`` makes the build copy the real 

37 on-disk bytes, so nothing is duplicated in the repository. The README 

38 inside ``images/`` is documentation for contributors, not a site asset. 

39 """ 

40 for path in sorted(_IMAGES_DIR.iterdir()): 

41 if not path.is_file() or path.name == "README.md": 

42 continue 

43 files.append( 

44 File.generated( 

45 config, 

46 src_uri=f"{_SITE_PREFIX}/{path.name}", 

47 abs_src_path=str(path), 

48 ) 

49 ) 

50 return files