mkdocs-ultralytics-plugin 0.2.4__tar.gz → 0.2.5__tar.gz

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.4
+Version: 0.2.5
 Summary: An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
 Author-email: Glenn Jocher <hello@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>
@@ -45,7 +45,7 @@ Dynamic: license-file
 
 # 🚀 MkDocs Ultralytics Plugin
 
-Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your [MkDocs](https://www.mkdocs.org/), [Zensical](https://zensical.com/), or any static site documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your documentation's visibility on the web.
+Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your [MkDocs](https://www.mkdocs.org/), [Zensical](https://zensical.org/), or any static site documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your documentation's visibility on the web.
 
 **Two modes available:**
 
@@ -64,12 +64,13 @@ This tool seamlessly integrates valuable features into your documentation site:
 
 - **Meta Tag Generation**: Automatically creates meta description and image tags using the first paragraph and image found on each page, crucial for SEO and social previews.
 - **Keyword Customization**: Allows you to define specific meta keywords directly within your Markdown front matter for targeted SEO.
-- **Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image) meta tags to ensure your content looks great when shared on social platforms.
+- **Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://docs.x.com/overview) meta tags to ensure your content looks great when shared on social platforms.
 - **Simple Sharing**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content, encouraging readers to share.
 - **Git Insights**: Gathers and displays [Git](https://git-scm.com/) commit information, including update dates and authors, directly within the page footer for transparency.
 - **JSON-LD Support**: Adds structured data in JSON-LD format, helping search engines understand your content better and potentially enabling rich results.
 - **FAQ Parsing**: Automatically parses FAQ sections (if present) and includes them in the structured data for enhanced search visibility.
 - **Copy for LLM**: Adds a button to copy page content in Markdown format, optimized for sharing with AI assistants.
+- **LLMs.txt Generation**: Generates an `llms.txt` index after builds for LLM-friendly site discovery.
 - **Customizable Styling**: Includes optional inline CSS to maintain consistent styling across your documentation, aligning with themes like [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
 
 ## 🛠️ Installation
@@ -177,6 +178,7 @@ Both modes support the same configuration options:
 | `add_json_ld`       | bool | `False` | Add JSON-LD structured data      |
 | `add_css`           | bool | `True`  | Include inline CSS styles        |
 | `add_copy_llm`      | bool | `True`  | Add "Copy for LLM" button        |
+| `add_llms_txt`      | bool | `True`  | Generate an `llms.txt` index     |
 
 ## 🧩 How It Works
 
@@ -244,7 +246,7 @@ Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributi
 
 Ultralytics provides two licensing options:
 
-- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-v3) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
+- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-3.0) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
 - **Enterprise License**: Designed for commercial applications, this license allows seamless integration of Ultralytics software into commercial products, bypassing AGPL-3.0 requirements. Visit [Ultralytics Licensing](https://www.ultralytics.com/license) for details.
 
 ## ✉️ Connect with Us
@@ -259,7 +261,7 @@ Encountered a bug or have an idea? Visit [GitHub Issues](https://github.com/ultr
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
   <a href="https://twitter.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-twitter.png" width="3%" alt="Ultralytics Twitter"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
-  <a href="https://youtube.com/ultralytics?sub_confirmation=1"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
+  <a href="https://www.youtube.com/ultralytics?sub_confirmation=1"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
   <a href="https://www.tiktok.com/@ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-tiktok.png" width="3%" alt="Ultralytics TikTok"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/README.md

@@ -2,7 +2,7 @@
 
 # 🚀 MkDocs Ultralytics Plugin
 
-Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your [MkDocs](https://www.mkdocs.org/), [Zensical](https://zensical.com/), or any static site documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your documentation's visibility on the web.
+Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your [MkDocs](https://www.mkdocs.org/), [Zensical](https://zensical.org/), or any static site documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your documentation's visibility on the web.
 
 **Two modes available:**
 
@@ -21,12 +21,13 @@ This tool seamlessly integrates valuable features into your documentation site:
 
 - **Meta Tag Generation**: Automatically creates meta description and image tags using the first paragraph and image found on each page, crucial for SEO and social previews.
 - **Keyword Customization**: Allows you to define specific meta keywords directly within your Markdown front matter for targeted SEO.
-- **Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image) meta tags to ensure your content looks great when shared on social platforms.
+- **Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://docs.x.com/overview) meta tags to ensure your content looks great when shared on social platforms.
 - **Simple Sharing**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content, encouraging readers to share.
 - **Git Insights**: Gathers and displays [Git](https://git-scm.com/) commit information, including update dates and authors, directly within the page footer for transparency.
 - **JSON-LD Support**: Adds structured data in JSON-LD format, helping search engines understand your content better and potentially enabling rich results.
 - **FAQ Parsing**: Automatically parses FAQ sections (if present) and includes them in the structured data for enhanced search visibility.
 - **Copy for LLM**: Adds a button to copy page content in Markdown format, optimized for sharing with AI assistants.
+- **LLMs.txt Generation**: Generates an `llms.txt` index after builds for LLM-friendly site discovery.
 - **Customizable Styling**: Includes optional inline CSS to maintain consistent styling across your documentation, aligning with themes like [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
 
 ## 🛠️ Installation
@@ -134,6 +135,7 @@ Both modes support the same configuration options:
 | `add_json_ld`       | bool | `False` | Add JSON-LD structured data      |
 | `add_css`           | bool | `True`  | Include inline CSS styles        |
 | `add_copy_llm`      | bool | `True`  | Add "Copy for LLM" button        |
+| `add_llms_txt`      | bool | `True`  | Generate an `llms.txt` index     |
 
 ## 🧩 How It Works
 
@@ -201,7 +203,7 @@ Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributi
 
 Ultralytics provides two licensing options:
 
-- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-v3) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
+- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-3.0) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
 - **Enterprise License**: Designed for commercial applications, this license allows seamless integration of Ultralytics software into commercial products, bypassing AGPL-3.0 requirements. Visit [Ultralytics Licensing](https://www.ultralytics.com/license) for details.
 
 ## ✉️ Connect with Us
@@ -216,7 +218,7 @@ Encountered a bug or have an idea? Visit [GitHub Issues](https://github.com/ultr
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
   <a href="https://twitter.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-twitter.png" width="3%" alt="Ultralytics Twitter"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
-  <a href="https://youtube.com/ultralytics?sub_confirmation=1"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
+  <a href="https://www.youtube.com/ultralytics?sub_confirmation=1"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
   <a href="https://www.tiktok.com/@ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-tiktok.png" width="3%" alt="Ultralytics TikTok"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/mkdocs_ultralytics_plugin.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.4
+Version: 0.2.5
 Summary: An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
 Author-email: Glenn Jocher <hello@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>
@@ -45,7 +45,7 @@ Dynamic: license-file
 
 # 🚀 MkDocs Ultralytics Plugin
 
-Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your [MkDocs](https://www.mkdocs.org/), [Zensical](https://zensical.com/), or any static site documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your documentation's visibility on the web.
+Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your [MkDocs](https://www.mkdocs.org/), [Zensical](https://zensical.org/), or any static site documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your documentation's visibility on the web.
 
 **Two modes available:**
 
@@ -64,12 +64,13 @@ This tool seamlessly integrates valuable features into your documentation site:
 
 - **Meta Tag Generation**: Automatically creates meta description and image tags using the first paragraph and image found on each page, crucial for SEO and social previews.
 - **Keyword Customization**: Allows you to define specific meta keywords directly within your Markdown front matter for targeted SEO.
-- **Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image) meta tags to ensure your content looks great when shared on social platforms.
+- **Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://docs.x.com/overview) meta tags to ensure your content looks great when shared on social platforms.
 - **Simple Sharing**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content, encouraging readers to share.
 - **Git Insights**: Gathers and displays [Git](https://git-scm.com/) commit information, including update dates and authors, directly within the page footer for transparency.
 - **JSON-LD Support**: Adds structured data in JSON-LD format, helping search engines understand your content better and potentially enabling rich results.
 - **FAQ Parsing**: Automatically parses FAQ sections (if present) and includes them in the structured data for enhanced search visibility.
 - **Copy for LLM**: Adds a button to copy page content in Markdown format, optimized for sharing with AI assistants.
+- **LLMs.txt Generation**: Generates an `llms.txt` index after builds for LLM-friendly site discovery.
 - **Customizable Styling**: Includes optional inline CSS to maintain consistent styling across your documentation, aligning with themes like [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
 
 ## 🛠️ Installation
@@ -177,6 +178,7 @@ Both modes support the same configuration options:
 | `add_json_ld`       | bool | `False` | Add JSON-LD structured data      |
 | `add_css`           | bool | `True`  | Include inline CSS styles        |
 | `add_copy_llm`      | bool | `True`  | Add "Copy for LLM" button        |
+| `add_llms_txt`      | bool | `True`  | Generate an `llms.txt` index     |
 
 ## 🧩 How It Works
 
@@ -244,7 +246,7 @@ Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributi
 
 Ultralytics provides two licensing options:
 
-- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-v3) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
+- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-3.0) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
 - **Enterprise License**: Designed for commercial applications, this license allows seamless integration of Ultralytics software into commercial products, bypassing AGPL-3.0 requirements. Visit [Ultralytics Licensing](https://www.ultralytics.com/license) for details.
 
 ## ✉️ Connect with Us
@@ -259,7 +261,7 @@ Encountered a bug or have an idea? Visit [GitHub Issues](https://github.com/ultr
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
   <a href="https://twitter.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-twitter.png" width="3%" alt="Ultralytics Twitter"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
-  <a href="https://youtube.com/ultralytics?sub_confirmation=1"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
+  <a href="https://www.youtube.com/ultralytics?sub_confirmation=1"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
   <a href="https://www.tiktok.com/@ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-tiktok.png" width="3%" alt="Ultralytics TikTok"></a>
   <img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/plugin/__init__.py

@@ -1,6 +1,6 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 
 from .main import MetaPlugin
 from .postprocess import postprocess_site

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/plugin/main.py

@@ -1,4 +1,5 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+"""MkDocs plugin entrypoint for Ultralytics documentation metadata."""
 
 from __future__ import annotations
 
@@ -9,6 +10,7 @@ from mkdocs.plugins import BasePlugin
 
 import plugin.processor as processor
 from plugin.processor import process_html
+from plugin.utils import resolve_all_authors
 
 
 class MetaPlugin(BasePlugin):
@@ -27,9 +29,11 @@ class MetaPlugin(BasePlugin):
         ("add_json_ld", config_options.Type(bool, default=False)),
         ("add_css", config_options.Type(bool, default=True)),
         ("add_copy_llm", config_options.Type(bool, default=True)),
+        ("add_llms_txt", config_options.Type(bool, default=True)),
     )
 
     def __init__(self):
+        """Initialize cached repository metadata for page processing."""
         super().__init__()
         self.git_repo_url = None
         self.git_data = None
@@ -43,6 +47,12 @@ class MetaPlugin(BasePlugin):
             docs_dir = Path(config["docs_dir"])
             md_files = [str(p) for p in docs_dir.rglob("*.md")] if docs_dir.exists() else []
             self.git_repo_url, self.git_data = processor.build_git_map(md_files)
+            self.git_data = resolve_all_authors(
+                self.git_data,
+                default_author=self.config.get("default_author"),
+                repo_url=self.git_repo_url,
+                verbose=self.config.get("verbose", True),
+            )
         return config
 
     def on_post_page(self, output: str, page, config) -> str:
@@ -69,7 +79,6 @@ class MetaPlugin(BasePlugin):
                 git_data=self.git_data,
                 repo_url=self.git_repo_url,
                 default_image=self.config["default_image"],
-                default_author=self.config["default_author"],
                 keywords=keywords,
                 add_desc=self.config["add_desc"],
                 add_image=self.config["add_image"],
@@ -84,3 +93,18 @@ class MetaPlugin(BasePlugin):
             if self.config["verbose"]:
                 print(f"ERROR - mkdocs-ultralytics-plugin: Failed to process {page.file.src_path}: {e}")
             return output  # Return original output on error
+
+    def on_post_build(self, config):
+        """Generate llms.txt after build completes. Added for mkdocs build compatibility. Not needed for zensical build."""
+        if not self.config.get("enabled", True) or not self.config.get("add_llms_txt", True):
+            return
+        from plugin.postprocess import generate_llms_txt
+
+        generate_llms_txt(
+            site_dir=Path(config["site_dir"]),
+            docs_dir=Path(config["docs_dir"]),
+            site_url=config.get("site_url", ""),
+            site_name=config.get("site_name"),
+            site_description=config.get("site_description"),
+            nav=config.get("nav"),
+        )

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/plugin/postprocess.py

@@ -134,6 +134,119 @@ def process_html_file(
         return False
 
 
+def generate_llms_txt(
+    site_dir: Path,
+    docs_dir: Path,
+    site_url: str,
+    site_name: str | None = None,
+    site_description: str | None = None,
+    nav: list | None = None,
+) -> None:
+    """Generate llms.txt file for LLM consumption."""
+    import yaml
+
+    # Fallback to reading mkdocs.yml if config values not provided (standalone postprocess mode)
+    if site_name is None or nav is None:
+
+        class _Loader(yaml.SafeLoader):
+            pass
+
+        _Loader.add_multi_constructor("", lambda loader, suffix, node: None)
+
+        mkdocs_yml = site_dir.parent / "mkdocs.yml"
+        if mkdocs_yml.exists():
+            config = yaml.load(mkdocs_yml.read_text(), Loader=_Loader) or {}
+            site_name = site_name or config.get("site_name", "Documentation")
+            site_description = site_description or config.get("site_description", "")
+            nav = nav or config.get("nav")
+    site_name = site_name or "Documentation"
+    site_description = site_description or ""
+
+    lines = [f"# {site_name}", f"> {site_description}"]
+    seen_urls: set[str] = set()
+    site_url = site_url.rstrip("/")
+
+    def get_description(md_path: Path) -> str:
+        """Extract description from markdown frontmatter."""
+        try:
+            content = md_path.read_text()
+            if content.startswith("---"):
+                end = content.find("\n---\n", 3)
+                if end != -1:
+                    fm = yaml.safe_load(content[4:end]) or {}
+                    return fm.get("description", "")
+        except Exception:
+            pass
+        return ""
+
+    def md_to_url(md_path: str) -> str:
+        """Convert markdown path to HTML URL."""
+        url = md_path.replace(".md", "/").replace("/index/", "/")
+        return f"{site_url}/{url}" if url != "index/" else f"{site_url}/"
+
+    if nav:
+
+        def process_items(items, indent=0):
+            """Recursively process nav items with indentation (Vercel-style)."""
+            prefix = "  " * indent + "- "
+            for item in items:
+                if isinstance(item, str):
+                    md = docs_dir / item
+                    if md.exists():
+                        url = md_to_url(item)
+                        if url in seen_urls:
+                            continue
+                        seen_urls.add(url)
+                        desc = get_description(md)
+                        # Use parent dir name for index.md, else filename
+                        title = md.parent.name if md.stem == "index" else md.stem
+                        title = title.replace("-", " ").replace("_", " ").title()
+                        desc_part = f": {desc}" if desc else ""
+                        lines.append(f"{prefix}[{title}]({url}){desc_part}")
+                elif isinstance(item, dict):
+                    for k, v in item.items():
+                        if isinstance(v, str):
+                            md = docs_dir / v
+                            if md.exists():
+                                url = md_to_url(v)
+                                if url in seen_urls:
+                                    continue
+                                seen_urls.add(url)
+                                desc = get_description(md)
+                                desc_part = f": {desc}" if desc else ""
+                                lines.append(f"{prefix}[{k}]({url}){desc_part}")
+                        elif isinstance(v, list):
+                            # Nested section - plain text header, then recurse
+                            lines.append(f"{prefix}{k}")
+                            process_items(v, indent + 1)
+
+        # Top-level nav items become ## sections
+        for item in nav:
+            if isinstance(item, str):
+                process_items([item], indent=0)
+            elif isinstance(item, dict):
+                for k, v in item.items():
+                    if isinstance(v, list):
+                        lines.extend(["", f"## {k}"])
+                        process_items(v, indent=0)
+                    else:
+                        process_items([{k: v}], indent=0)
+    else:
+        for md in sorted(docs_dir.rglob("*.md")):
+            rel = md.relative_to(docs_dir).as_posix()
+            url = md_to_url(rel)
+            if url in seen_urls:
+                continue
+            seen_urls.add(url)
+            desc = get_description(md)
+            title = md.stem.replace("-", " ").replace("_", " ").title()
+            desc_part = f": {desc}" if desc else ""
+            lines.append(f"- [{title}]({url}){desc_part}")
+
+    (site_dir / "llms.txt").write_text("\n".join(lines))
+    print("Generated llms.txt")
+
+
 def postprocess_site(
     site_dir: str | Path = "site",
     docs_dir: str | Path = "docs",
@@ -148,6 +261,7 @@ def postprocess_site(
     add_json_ld: bool = False,
     add_css: bool = True,
     add_copy_llm: bool = True,
+    add_llms_txt: bool = True,
     verbose: bool = True,
     use_processes: bool = True,
     workers: int | None = None,
@@ -250,6 +364,9 @@ def postprocess_site(
 
     print(f"✅ Postprocessing complete: {processed}/{len(html_files)} files processed")
 
+    if add_llms_txt:
+        generate_llms_txt(site_dir, docs_dir, site_url)
+
 
 if __name__ == "__main__":
     postprocess_site()

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/plugin/processor.py

@@ -136,7 +136,7 @@ def build_git_map(file_paths: list[str] | list[Path]) -> tuple[str | None, dict[
         str(repo_root),
         "log",
         "--name-only",
-        "--pretty=format:%ad\t%ae",
+        "--pretty=format:%H\t%ad\t%ae",
         "--date=format:%Y-%m-%d %H:%M:%S %z",
         "--",
         *[str(p) for p in rel_paths],
@@ -147,17 +147,18 @@ def build_git_map(file_paths: list[str] | list[Path]) -> tuple[str | None, dict[
     except subprocess.CalledProcessError:
         return repo_url, git_data
 
+    current_commit = None
     current_date = None
     current_email = None
     for line in output:
         if not line.strip():
             continue
         parts = line.split("\t")
-        if len(parts) == 2:
-            current_date, current_email = parts
+        if len(parts) == 3:
+            current_commit, current_date, current_email = parts
             continue
 
-        if current_date and current_email:
+        if current_commit and current_date and current_email:
             abs_path = (repo_root / line.strip()).resolve()
             key = str(abs_path)
             entry = git_data.setdefault(
@@ -166,11 +167,13 @@ def build_git_map(file_paths: list[str] | list[Path]) -> tuple[str | None, dict[
                     "creation_date": current_date,
                     "last_modified_date": current_date,
                     "emails": {},
+                    "commits": {},
                 },
             )
             entry.setdefault("last_modified_date", current_date)
             entry["creation_date"] = current_date
             entry["emails"][current_email] = entry["emails"].get(current_email, 0) + 1
+            entry["commits"].setdefault(current_email, current_commit)
 
     return repo_url, git_data
 
@@ -436,21 +439,22 @@ def process_html(
                 let rawUrl = editBtn.href.replace('github.com', 'raw.githubusercontent.com');
                 rawUrl = rawUrl.replace('/blob/', '/').replace('/tree/', '/');
 
-                try {{
+                async function getContent() {{
                     const response = await fetch(rawUrl);
                     let markdown = await response.text();
-
                     if (markdown.startsWith('---')) {{
                         const frontMatterEnd = markdown.indexOf('\\n---\\n', 3);
-                        if (frontMatterEnd !== -1) {{
-                            markdown = markdown.substring(frontMatterEnd + 5).trim();
-                        }}
+                        if (frontMatterEnd !== -1) markdown = markdown.substring(frontMatterEnd + 5).trim();
                     }}
-
                     const title = document.querySelector('h1')?.textContent || document.title;
-                    const content = `# ${{title}}\\n\\nSource: ${{window.location.href}}\\n\\n---\\n\\n${{markdown}}`;
+                    return `# ${{title}}\\n\\nSource: ${{window.location.href}}\\n\\n---\\n\\n${{markdown}}`;
+                }}
 
-                    await navigator.clipboard.writeText(content);
+                try {{
+                    const clipboardItem = new ClipboardItem({{
+                        'text/plain': getContent().then(text => new Blob([text], {{ type: 'text/plain' }}))
+                    }});
+                    await navigator.clipboard.write([clipboardItem]);
                     button.innerHTML = checkIcon + ' Copied!';
                     setTimeout(() => {{ button.innerHTML = originalHTML; }}, 2000);
                 }} catch (err) {{

{mkdocs_ultralytics_plugin-0.2.4 → mkdocs_ultralytics_plugin-0.2.5}/plugin/utils.py

@@ -6,6 +6,7 @@ import re
 from datetime import datetime
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlparse
 
 import requests
 import yaml
@@ -97,14 +98,31 @@ def save_author_cache(cache: dict[str, dict[str, str | None]]) -> None:
         print(f"{WARNING} Failed to save author cache: {e}")
 
 
+def _github_repo_path(repo_url: str | None) -> str | None:
+    """Return the owner/repo path for a GitHub repository URL."""
+    if not repo_url:
+        return None
+    parsed = urlparse(repo_url)
+    if parsed.hostname != "github.com":
+        return None
+    path = parsed.path.strip("/")
+    return path[:-4] if path.endswith(".git") else path or None
+
+
 def resolve_github_user(
-    email: str, cache: dict[str, dict[str, str | None]], verbose: bool = True
+    email: str,
+    cache: dict[str, dict[str, str | None]],
+    repo_url: str | None = None,
+    commit_sha: str | None = None,
+    verbose: bool = True,
 ) -> dict[str, str | None]:
     """Resolve a single email to GitHub username and avatar, updating cache in-place.
 
     Args:
         email (str): The email address to resolve.
         cache (dict): The author cache dict (modified in-place if new entry added).
+        repo_url (str, optional): GitHub repository URL used for commit API fallback.
+        commit_sha (str, optional): Commit SHA authored by the email.
         verbose (bool): Whether to print API call info.
 
     Returns:
@@ -113,8 +131,8 @@ def resolve_github_user(
     if not email or not email.strip():
         return {"username": None, "avatar": None}
 
-    # Return cached result if available
-    if email in cache:
+    # Return complete cached results immediately. Incomplete cached entries may be refreshed from commit metadata.
+    if email in cache and cache[email].get("username") and cache[email].get("avatar"):
         return cache[email]
 
     # Parse username directly from GitHub noreply emails
@@ -127,6 +145,23 @@ def resolve_github_user(
         cache[email] = {"username": username, "avatar": avatar}
         return cache[email]
 
+    # Query the commit API when git history provides a commit for this email. This resolves authors whose commit email
+    # is linked to a GitHub account but hidden from user search.
+    if repo_path := _github_repo_path(repo_url):
+        if commit_sha:
+            try:
+                response = requests.get(
+                    f"https://api.github.com/repos/{repo_path}/commits/{commit_sha}", timeout=TIMEOUT
+                )
+                if response.status_code == 200:
+                    data = response.json()
+                    author = data.get("author") or {}
+                    if author.get("login") and author.get("avatar_url"):
+                        cache[email] = {"username": author["login"], "avatar": author["avatar_url"]}
+                        return cache[email]
+            except Exception:
+                pass
+
     # Query GitHub REST API
     if verbose:
         print(f"Running GitHub REST API for author {email}")
@@ -173,10 +208,13 @@ def resolve_all_authors(
     if not git_data:
         return git_data
 
-    # Collect all unique emails across all files
+    # Collect all unique emails across all files, with one representative commit SHA per email.
     all_emails: set[str] = set()
+    commits: dict[str, str] = {}
     for entry in git_data.values():
         all_emails.update(entry.get("emails", {}).keys())
+        for email, commit in entry.get("commits", {}).items():
+            commits.setdefault(email, commit)
     if default_author:
         all_emails.add(default_author)
     all_emails.discard("")
@@ -189,8 +227,9 @@ def resolve_all_authors(
     cache_modified = False
 
     for email in sorted(all_emails):
-        if email not in cache:
-            resolve_github_user(email, cache, verbose=verbose)
+        cached = cache.get(email, {})
+        if email not in cache or (commits.get(email) and not (cached.get("username") and cached.get("avatar"))):
+            resolve_github_user(email, cache, repo_url=repo_url, commit_sha=commits.get(email), verbose=verbose)
             cache_modified = True
 
     if cache_modified: