docs: tighten llms_txt failure modes and name embedded snippet sources

Unresolvable relative .md links and pages that do not start with an H1
now fail the build instead of producing broken or malformed renditions.
Embedded .py snippets gain a leading comment naming the source file,
so the rendition still points at the file on disk.

Author: maxisbey

docs/hooks/llms_txt.py

@@ -90,6 +90,9 @@ def include(match: re.Match[str]) -> str:
             content = resolved_path.read_text(encoding="utf-8").rstrip("\n")
         except OSError as exc:
             raise PluginError(f"llms_txt: cannot read snippet {path!r} in {page.file.src_uri}") from exc
+        # Keep a pointer to the embedded file so readers can find it on disk.
+        if path.endswith(".py"):
+            content = f"# {path}\n{content}"
         if indent:
             content = "\n".join(indent + line if line else line for line in content.split("\n"))
         return content
@@ -107,7 +110,7 @@ def rewrite(match: re.Match[str]) -> str:
             return match.group(0)
         linked = files.get_file_from_path(posixpath.normpath(posixpath.join(src_dir, target)))
         if linked is None:
-            return match.group(0)
+            raise PluginError(f"llms_txt: cannot resolve link target {target!r} in {page.file.src_uri}")
         # Pages without a markdown rendition (the api.md stub) link to their HTML instead.
         url = _md_uri(linked) if linked.src_uri in _state.rendition_uris else linked.url
         return f"{opening}{site_url}{url}{anchor or ''}{title or ''}{closing}"
@@ -157,7 +160,9 @@ def on_post_build(config: MkDocsConfig) -> None:
             tail = f": {description}" if description else ""
             index.append(f"- [{page.title}]({site_url}{_md_uri(page.file)}){tail}")
 
-            body = re.sub(r"\A\s*# .+\n", "", markdown)
+            body, h1_found = re.subn(r"\A\s*# .+\n", "", markdown)
+            if not h1_found:
+                raise PluginError(f"llms_txt: page {page.file.src_uri} does not start with an H1")
             full += [f"# {page.title}", "", f"Source: {page.canonical_url}", "", body.strip(), ""]
         index.append("")