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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.3
+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.3 → 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.3 → 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.3
+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.3 → 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.3"
+__version__ = "0.2.5"
 
 from .main import MetaPlugin
 from .postprocess import postprocess_site

{mkdocs_ultralytics_plugin-0.2.3 → 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.3 → mkdocs_ultralytics_plugin-0.2.5}/plugin/postprocess.py

@@ -16,6 +16,7 @@ except ImportError:
 
 import plugin.processor as processor
 from plugin.processor import process_html
+from plugin.utils import resolve_all_authors
 
 # Shared worker state for process pools (avoids re-pickling large read-only data per task)
 _WORKER_STATE: dict[str, Any] | None = None
@@ -37,7 +38,6 @@ def _process_file(html_file: Path) -> bool:
         _WORKER_STATE["repo_url"],
         site_url=_WORKER_STATE["site_url"],
         default_image=_WORKER_STATE["default_image"],
-        default_author=_WORKER_STATE["default_author"],
         add_desc=_WORKER_STATE["add_desc"],
         add_image=_WORKER_STATE["add_image"],
         add_keywords=_WORKER_STATE["add_keywords"],
@@ -59,7 +59,6 @@ def process_html_file(
     repo_url: str | None,
     site_url: str = "",
     default_image: str | None = None,
-    default_author: str | None = None,
     add_desc: bool = True,
     add_image: bool = True,
     add_keywords: bool = True,
@@ -114,7 +113,6 @@ def process_html_file(
         git_data=git_data,
         repo_url=repo_url,
         default_image=default_image,
-        default_author=default_author,
         keywords=keywords,
         add_desc=add_desc,
         add_image=add_image,
@@ -136,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",
@@ -150,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,
@@ -184,6 +296,9 @@ def postprocess_site(
     git_data = None
     if (add_authors or add_json_ld) and md_index:
         repo_url, git_data = processor.build_git_map(list(md_index.values()))
+        # Resolve all authors ONCE in main process before spawning workers
+        # This prevents race conditions when workers try to write to the cache file
+        git_data = resolve_all_authors(git_data, default_author=default_author, repo_url=repo_url, verbose=verbose)
 
     progress = TQDM(total=len(html_files), desc="Postprocessing", unit="file", disable=not verbose) if TQDM else None
     # Enable logging only for the synchronous path; pools run without per-task log_fn to remain pickle-safe.
@@ -196,7 +311,6 @@ def postprocess_site(
         repo_url=repo_url,
         site_url=site_url,
         default_image=default_image,
-        default_author=default_author,
         add_desc=add_desc,
         add_image=add_image,
         add_keywords=add_keywords,
@@ -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.3 → mkdocs_ultralytics_plugin-0.2.5}/plugin/processor.py

@@ -13,11 +13,7 @@ from urllib.parse import quote
 
 from bs4 import BeautifulSoup
 
-from plugin.utils import (
-    calculate_time_difference,
-    get_github_usernames_from_file,
-    get_youtube_video_ids,
-)
+from plugin.utils import calculate_time_difference, get_youtube_video_ids
 
 today = datetime.now()
 DEFAULT_CREATION_DATE = (today - timedelta(days=365)).strftime("%Y-%m-%d %H:%M:%S +0000")
@@ -30,11 +26,9 @@ CHECK_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path
 def get_git_info(
     file_path: str,
     add_authors: bool = True,
-    default_author: str | None = None,
     git_data: dict[str, dict[str, Any]] | None = None,
-    repo_url: str | None = None,
 ) -> dict[str, Any]:
-    """Retrieve git information (dates + optional authors) from precomputed git data."""
+    """Retrieve git information (dates + pre-resolved authors) from precomputed git data."""
     file_path = str(Path(file_path).resolve())
     git_info = {
         "creation_date": DEFAULT_CREATION_DATE,
@@ -45,29 +39,12 @@ def get_git_info(
         return git_info
 
     cached = git_data[file_path]
-    git_info.update(
-        {
-            "creation_date": cached.get("creation_date", DEFAULT_CREATION_DATE),
-            "last_modified_date": cached.get("last_modified_date", DEFAULT_MODIFIED_DATE),
-        }
-    )
-
-    if add_authors and cached.get("emails"):
-        git_info["authors"] = sorted(
-            [
-                (
-                    author,
-                    info["url"],
-                    info["changes"],
-                    info["avatar"],
-                )
-                for author, info in get_github_usernames_from_file(
-                    file_path, default_user=default_author, emails=cached["emails"], repo_url=repo_url
-                ).items()
-            ],
-            key=lambda x: x[2],
-            reverse=True,
-        )
+    git_info["creation_date"] = cached.get("creation_date", DEFAULT_CREATION_DATE)
+    git_info["last_modified_date"] = cached.get("last_modified_date", DEFAULT_MODIFIED_DATE)
+
+    # Authors are pre-resolved by resolve_all_authors() in the main process
+    if add_authors and "authors" in cached:
+        git_info["authors"] = cached["authors"]
 
     return git_info
 
@@ -159,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],
@@ -170,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(
@@ -189,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
 
@@ -309,7 +289,6 @@ def process_html(
     git_data: dict[str, dict[str, Any]] | None = None,
     repo_url: str | None = None,
     default_image: str | None = None,
-    default_author: str | None = None,
     keywords: str | None = None,
     add_desc: bool = True,
     add_image: bool = True,
@@ -460,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) {{
@@ -493,9 +473,7 @@ def process_html(
     needs_git = (add_authors or add_json_ld) and src_path
 
     if needs_git:
-        git_info = get_git_info(
-            src_path, add_authors=add_authors, default_author=default_author, git_data=git_data, repo_url=repo_url
-        )
+        git_info = get_git_info(src_path, add_authors=add_authors, git_data=git_data)
 
         # Only render git footer if we have real git history (not placeholder defaults)
         has_real_git_data = (

mkdocs_ultralytics_plugin-0.2.5/plugin/utils.py

@@ -0,0 +1,262 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+import yaml
+
+WARNING = "WARNING (mkdocs_ultralytics_plugin):"
+TIMEOUT = 10  # seconds for network requests
+DEFAULT_AVATAR_URL = "https://github.com/github.png"
+_default_avatar_cache: str | None = None
+
+
+def get_default_avatar() -> str:
+    """Get the default avatar URL, lazily fetching the resolved URL on first call."""
+    global _default_avatar_cache
+    if _default_avatar_cache is None:
+        try:
+            _default_avatar_cache = requests.head(DEFAULT_AVATAR_URL, allow_redirects=True, timeout=TIMEOUT).url
+        except Exception:
+            _default_avatar_cache = DEFAULT_AVATAR_URL  # fallback to original URL
+    return _default_avatar_cache
+
+
+def calculate_time_difference(date_string: str) -> tuple[str, str]:
+    """Calculate the time difference between a given date and the current date in a human-readable format.
+
+    Args:
+        date_string (str): Date and time string in the format "%Y-%m-%d %H:%M:%S %z".
+
+    Returns:
+        difference (str): Time difference in days, months, or years (e.g., "5 days", "2 months", "1 year").
+        pretty_date (str): Given date formatted as "Month Day, Year" (e.g., "January 01, 2023").
+
+    Examples:
+        >>> calculate_time_difference("2023-01-01 00:00:00 +0000")
+        ("5 months", "January 01, 2023")
+    """
+    date = datetime.strptime(date_string, "%Y-%m-%d %H:%M:%S %z")
+    pretty_date = date.strftime("%B %d, %Y")
+    now = datetime.now(date.tzinfo)
+    diff = now - date
+    days = diff.days
+
+    if days < 30:
+        difference = f"{days} day{'s' if days != 1 else ''}"
+    elif days < 365:
+        months = days // 30
+        difference = f"{months} month{'s' if months != 1 else ''}"
+    else:
+        years = days // 365
+        difference = f"{years} year{'s' if years != 1 else ''}"
+    return difference, pretty_date
+
+
+def get_youtube_video_ids(soup) -> list[str]:
+    """Extract YouTube video IDs from iframe elements present in the provided BeautifulSoup object.
+
+    Args:
+        soup (BeautifulSoup): A BeautifulSoup object containing the HTML content.
+
+    Returns:
+        (List[str]): A list containing YouTube video IDs extracted from the HTML content.
+    """
+    youtube_ids = []
+    iframes = soup.find_all("iframe", src=True)
+    for iframe in iframes:
+        if match := re.search(r"youtube\.com/embed/([a-zA-Z0-9_-]+)", iframe["src"]):
+            youtube_ids.append(match[1])
+    return youtube_ids
+
+
+def _get_cache_file() -> Path:
+    """Get the path to the GitHub author cache file."""
+    return Path("docs" if Path("docs").is_dir() else "") / "mkdocs_github_authors.yaml"
+
+
+def load_author_cache() -> dict[str, dict[str, str | None]]:
+    """Load the GitHub author cache from disk."""
+    cache_file = _get_cache_file()
+    try:
+        return yaml.safe_load(cache_file.read_text()) or {} if cache_file.is_file() else {}
+    except Exception:
+        return {}
+
+
+def save_author_cache(cache: dict[str, dict[str, str | None]]) -> None:
+    """Save the GitHub author cache to disk."""
+    try:
+        _get_cache_file().write_text(yaml.safe_dump(cache))
+    except Exception as e:
+        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]],
+    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:
+        dict with 'username' and 'avatar' keys (values may be None if not found).
+    """
+    if not email or not email.strip():
+        return {"username": None, "avatar": None}
+
+    # 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
+    if email.endswith("@users.noreply.github.com"):
+        username = email.split("+")[-1].split("@")[0]
+        try:
+            avatar = requests.head(f"https://github.com/{username}.png", allow_redirects=True, timeout=TIMEOUT).url
+        except Exception:
+            avatar = None
+        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}")
+    try:
+        response = requests.get(
+            f"https://api.github.com/search/users?q={email}+in:email&sort=joined&order=asc", timeout=TIMEOUT
+        )
+        if response.status_code == 200:
+            data = response.json()
+            if data.get("total_count", 0) > 0:
+                username = data["items"][0]["login"]
+                avatar = requests.head(data["items"][0]["avatar_url"], allow_redirects=True, timeout=TIMEOUT).url
+                cache[email] = {"username": username, "avatar": avatar}
+                return cache[email]
+    except Exception:
+        pass
+
+    if verbose:
+        print(f"{WARNING} No username found for {email}")
+    cache[email] = {"username": None, "avatar": None}
+    return cache[email]
+
+
+def resolve_all_authors(
+    git_data: dict[str, dict[str, Any]],
+    default_author: str | None = None,
+    repo_url: str | None = None,
+    verbose: bool = True,
+) -> dict[str, dict[str, Any]]:
+    """Pre-resolve all unique emails from git_data to GitHub usernames.
+
+    This should be called ONCE in the main process before spawning workers. It collects all unique emails, resolves
+    them, saves the cache, and returns git_data with 'authors' pre-populated for each file.
+
+    Args:
+        git_data (dict): The git metadata dict from build_git_map().
+        default_author (str, optional): Default author email if no git info.
+        repo_url (str, optional): Repository URL for fallback links.
+        verbose (bool): Whether to print progress info.
+
+    Returns:
+        dict: Updated git_data with 'authors' list added to each entry.
+    """
+    if not git_data:
+        return git_data
+
+    # 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("")
+
+    if not all_emails:
+        return git_data
+
+    # Load cache, resolve all emails, save cache (single disk write)
+    cache = load_author_cache()
+    cache_modified = False
+
+    for email in sorted(all_emails):
+        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:
+        save_author_cache(cache)
+
+    # Build authors list for each file entry
+    github_repo_url = repo_url or "https://github.com/ultralytics/ultralytics"
+
+    for file_path, entry in git_data.items():
+        emails = entry.get("emails", {})
+        if not emails and default_author:
+            emails = {default_author: 1}
+
+        authors = []
+        for email, changes in emails.items():
+            email = email.strip() if email else ""
+            if not email:
+                email = default_author or ""
+            if not email:
+                continue
+            info = cache.get(email, {"username": None, "avatar": None})
+            username = info.get("username")
+            avatar = info.get("avatar") or get_default_avatar()
+            user_url = f"https://github.com/{username}" if username else github_repo_url
+            authors.append((username or email, user_url, changes, avatar))
+
+        # Sort by number of changes (descending)
+        entry["authors"] = sorted(authors, key=lambda x: x[2], reverse=True)
+
+    return git_data

mkdocs_ultralytics_plugin-0.2.3/plugin/utils.py

@@ -1,236 +0,0 @@
-# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
-
-from __future__ import annotations
-
-import re
-import threading
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-import requests
-import yaml  # YAML is used for its readability and consistency with MkDocs ecosystem
-from bs4 import BeautifulSoup
-
-WARNING = "WARNING (mkdocs_ultralytics_plugin):"
-DEFAULT_AVATAR = requests.head("https://github.com/github.png", allow_redirects=True).url
-
-# Shared, thread-safe cache to avoid duplicate API lookups and YAML thrash when running in parallel
-_AUTHOR_CACHE: dict[str, dict[str, str | None]] | None = None
-_AUTHOR_CACHE_MTIME: float | None = None
-_CACHE_LOCK = threading.Lock()
-
-
-def calculate_time_difference(date_string: str) -> tuple[str, str]:
-    """Calculate the time difference between a given date and the current date in a human-readable format.
-
-    Args:
-        date_string (str): Date and time string in the format "%Y-%m-%d %H:%M:%S %z".
-
-    Returns:
-        difference (str): Time difference in days, months, or years (e.g., "5 days", "2 months", "1 year").
-        pretty_date (str): Given date formatted as "Month Day, Year" (e.g., "January 01, 2023").
-
-    Examples:
-        >>> calculate_time_difference("2023-01-01 00:00:00 +0000")
-        ("5 months", "January 01, 2023")
-    """
-    date = datetime.strptime(date_string, "%Y-%m-%d %H:%M:%S %z")
-    pretty_date = date.strftime("%B %d, %Y")
-    now = datetime.now(date.tzinfo)
-    diff = now - date
-    days = diff.days
-
-    if days < 30:
-        difference = f"{days} day{'s' if days != 1 else ''}"
-    elif days < 365:
-        months = days // 30
-        difference = f"{months} month{'s' if months != 1 else ''}"
-    else:
-        years = days // 365
-        difference = f"{years} year{'s' if years != 1 else ''}"
-    return difference, pretty_date
-
-
-def get_youtube_video_ids(soup: BeautifulSoup) -> list[str]:
-    """Extract YouTube video IDs from iframe elements present in the provided BeautifulSoup object.
-
-    Args:
-        soup (BeautifulSoup): A BeautifulSoup object containing the HTML content from which YouTube video IDs need to be
-            extracted.
-
-    Returns:
-        (List[str]): A list containing YouTube video IDs extracted from the HTML content.
-
-    Examples:
-        >>> from bs4 import BeautifulSoup
-        >>> html_content = '''
-        ... <html>
-        ...     <body>
-        ...         <iframe src="https://www.youtube.com/embed/example_id1"></iframe>
-        ...         <iframe src="https://www.youtube.com/embed/example_id2"></iframe>
-        ...     </body>
-        ... </html>
-        ... '''
-        >>> soup = BeautifulSoup(html_content, 'html.parser')
-        >>> video_ids = get_youtube_video_ids(soup)
-        >>> print(video_ids)
-        ['example_id1', 'example_id2']
-    """
-    youtube_ids = []
-    iframes = soup.find_all("iframe", src=True)
-    for iframe in iframes:
-        if match := re.search(r"youtube\.com/embed/([a-zA-Z0-9_-]+)", iframe["src"]):
-            youtube_ids.append(match[1])
-    return youtube_ids
-
-
-def get_github_username_from_email(
-    email: str, cache: dict, file_path: str = "", verbose: bool = True
-) -> tuple[str | None, str | None]:
-    """Retrieve the GitHub username and avatar URL associated with the given email address.
-
-    Args:
-        email (str): The email address to retrieve the GitHub username for.
-        cache (Dict): A dictionary containing cached email-GitHub username mappings.
-        file_path (str, optional): Name of the file the user authored.
-        verbose (bool, optional): Whether to print verbose output.
-
-    Returns:
-        username (str | None): GitHub username if found, None otherwise.
-        avatar (str | None): Avatar URL if found, None otherwise.
-
-    Notes:
-        If the email ends with "@users.noreply.github.com", the function will parse the username directly from the
-        email address. Uses the GitHub REST API to query the username if it's not found in the local cache. Ensure
-        you comply with GitHub's rate limits and authentication requirements when querying their API.
-    """
-    # First, check if the email exists in the local cache file
-    with _CACHE_LOCK:
-        if email in cache:
-            return cache[email].get("username"), cache[email].get("avatar")
-    if not email.strip():
-        if verbose:
-            print(f"{WARNING} No author found for {file_path}")
-        return None, None
-
-    # If the email ends with "@users.noreply.github.com", parse the username directly
-    if email.endswith("@users.noreply.github.com"):
-        username = email.split("+")[-1].split("@")[0]
-        avatar = f"https://github.com/{username}.png"
-        avatar_url = requests.head(avatar, allow_redirects=True).url
-        with _CACHE_LOCK:
-            cache[email] = {
-                "username": username,
-                "avatar": avatar_url,
-            }
-        return username, avatar
-
-    # Fallback to GitHub REST API when not cached
-    url = f"https://api.github.com/search/users?q={email}+in:email&sort=joined&order=asc"
-    if verbose:
-        print(f"Running GitHub REST API for author {email}")
-    response = requests.get(url)
-    if response.status_code == 200:
-        data = response.json()
-        if data["total_count"] > 0:
-            username = data["items"][0]["login"]
-            avatar = data["items"][0]["avatar_url"]  # avatar_url key is correct here
-            avatar_url = requests.head(avatar, allow_redirects=True).url
-            with _CACHE_LOCK:
-                cache[email] = {
-                    "username": username,
-                    "avatar": avatar_url,
-                }
-            return username, avatar
-
-    if verbose:
-        print(f"{WARNING} No username found for {email}")
-    with _CACHE_LOCK:
-        cache[email] = {"username": None, "avatar": None}
-    return None, None
-
-
-def get_github_usernames_from_file(
-    file_path: str,
-    default_user: str | None = None,
-    emails: dict[str, int] | None = None,
-    repo_url: str | None = None,
-    force_reload: bool = False,
-) -> dict[str, dict[str, Any]]:
-    """Fetch GitHub usernames associated with a file using provided Git email counts.
-
-    Args:
-        file_path (str): The path to the file for which GitHub usernames are to be retrieved.
-        default_user (str, optional): Default GitHub user email to use if no authors found.
-
-    Returns:
-        (Dict[str, Dict[str, any]]): A dictionary where keys are GitHub usernames or emails (if username is not
-            found) and values are dictionaries containing:
-            - 'email' (str): The email address of the author.
-            - 'url' (str): The GitHub profile URL of the author.
-            - 'changes' (int): The number of changes (commits) made by the author.
-            - 'avatar' (str): The URL of the author's GitHub avatar.
-
-    Examples:
-        >>> print(get_github_usernames_from_file('mkdocs.yml', emails={'user@example.com': 2}))
-        {'username1': {'email': 'user@example.com', 'url': 'https://github.com/username1', 'changes': 2, 'avatar': '...'}}
-    """
-    if emails is None:
-        emails = {}
-    else:
-        emails = dict(emails)  # shallow copy to avoid mutating caller data
-
-    # If no git info found but default_user provided, use default_user
-    if not emails and default_user:
-        emails[default_user] = 1
-
-    # Load the local cache of GitHub usernames once per process (thread-safe, reload if changed)
-    local_cache_file = Path("docs" if Path("docs").is_dir() else "") / "mkdocs_github_authors.yaml"
-    global _AUTHOR_CACHE, _AUTHOR_CACHE_MTIME
-    with _CACHE_LOCK:
-        current_mtime = local_cache_file.stat().st_mtime if local_cache_file.is_file() else None
-        needs_reload = (
-            force_reload
-            or _AUTHOR_CACHE is None
-            or (_AUTHOR_CACHE_MTIME is not None and current_mtime is not None and _AUTHOR_CACHE_MTIME != current_mtime)
-        )
-        if needs_reload:
-            if local_cache_file.is_file():
-                with local_cache_file.open("r") as f:
-                    _AUTHOR_CACHE = yaml.safe_load(f) or {}
-                _AUTHOR_CACHE_MTIME = local_cache_file.stat().st_mtime
-            else:
-                _AUTHOR_CACHE = {}
-                _AUTHOR_CACHE_MTIME = None
-        cache = _AUTHOR_CACHE
-
-    github_repo_url = repo_url or "https://github.com/ultralytics/ultralytics"
-
-    info = {}
-    cache_updated = False
-    for email, changes in emails.items():
-        if not email and default_user:
-            email = default_user
-        was_cached = email in cache
-        prev_entry = cache.get(email)
-        username, avatar = get_github_username_from_email(email, cache, file_path)
-        # If we can't determine the user URL, revert to the GitHub file URL
-        user_url = f"https://github.com/{username}" if username else github_repo_url
-        info[username or email] = {
-            "email": email,
-            "url": user_url,
-            "changes": changes,
-            "avatar": avatar or DEFAULT_AVATAR,
-        }
-        cache_updated = cache_updated or (email in cache and not was_cached) or cache.get(email) != prev_entry
-
-    # Save the local cache of GitHub usernames and avatar URLs if updated
-    if cache_updated:
-        with _CACHE_LOCK:
-            _AUTHOR_CACHE = cache
-            with local_cache_file.open("w") as f:
-                yaml.safe_dump(cache, f)
-            _AUTHOR_CACHE_MTIME = local_cache_file.stat().st_mtime
-
-    return info