v0.2.4 - Fix race condition on GitHub authors (#177)

🌟 Summary

v0.2.4 makes the MkDocs Ultralytics plugin more reliable and stable by fixing a GitHub author resolution race condition and modernizing the CI workflow dependencies. 🧱✨

---

📊 Key Changes

• 🧵 Race-condition fix for GitHub authors (PR #177 by @glenn-jocher)

  • GitHub author info is now resolved once in the main process via resolve_all_authors() before any multiprocessing begins.
  • Worker processes now only read precomputed author data from git_data—they no longer write to the author cache.
  • The previous global, thread-locked cache has been replaced with a clear load / resolve / save flow using:
    • load_author_cache()
    • resolve_github_user() / resolve_all_authors()
    • save_author_cache()
  • processor.get_git_info() and process_html() are simplified: they no longer accept default_author and repo-specific author parameters, and now just read pre-resolved authors.

• 💾 Safer and more robust author caching logic

  • Author cache is stored in a single YAML file: mkdocs_github_authors.yaml.
  • Cache is now updated once per run in the main process, avoiding concurrent writes and file corruption.
  • A new helper get_default_avatar() lazily fetches and caches the GitHub default avatar URL, with timeouts and fallbacks for network errors.

• 🌐 More resilient GitHub API calls

  • All GitHub-related HTTP calls now use a fixed timeout to prevent hangs.
  • Graceful fallbacks:
    • If avatar resolution fails, the plugin falls back to a safe default avatar URL.
    • If GitHub user lookup fails, authors are still rendered with sensible defaults (e.g., repo URL instead of profile URL).

• 🧹 Codebase cleanup and simplification

  • Utility functions simplified and tightened:
    • get_youtube_video_ids() signature and docstring streamlined.
  • get_git_info() now clearly:
    • Uses precomputed creation_date and last_modified_date.
    • Reads authors directly from the already-resolved git_data.

• ⚙️ CI workflow updates for GitHub Actions

  • actions/checkout upgraded from v5 → v6.
  • actions/upload-artifact upgraded from v5 → v6.
  • actions/download-artifact upgraded from v6 → v7.
  • These updates move the workflows to Node.js 24–based actions, keeping the release pipeline modern and compatible with the latest GitHub infrastructure.

---

🎯 Purpose & Impact

• 🚫 Eliminates intermittent build failures

  • The previous design allowed multiple parallel workers to write to mkdocs_github_authors.yaml at the same time, causing race conditions and occasional cache corruption.
  • By resolving authors once in the main process and making workers read-only, v0.2.4 removes this entire class of errors.

• ✅ More reliable documentation builds

  • MkDocs sites using this plugin (especially with multiprocessing enabled) will now build more consistently and predictably, with fewer hard-to-reproduce failures.
  • Teams running CI builds or automated doc deployments benefit from higher stability and less flakiness.

• 🧠 Simpler mental model for contributors

  • Author resolution now follows a straightforward pipeline:
    1. Build git map.
    2. Pre-resolve all authors in the main process.
    3. Save a single cache file.
    4. Let workers consume read-only git_data.
  • This makes the code easier to understand, maintain, and extend for future features.

• 🌍 Better behavior in real-world environments

  • Network errors, slow GitHub responses, or avatar resolution issues are now handled gracefully with timeouts and fallbacks, avoiding long hangs or crashes during docs builds.

• 🔒 Future-proof CI & tooling

  • Updating to the latest actions/* versions means:
    • Continued support for GitHub-hosted runners and modern Node.js versions.
    • Fewer surprises as older action versions are deprecated.
  • This keeps the publish pipeline for the plugin secure, current, and maintainable.

Overall, v0.2.4 is a stability and robustness release: no user-facing configuration changes are required, but your MkDocs builds using the Ultralytics plugin should now be more dependable and less error-prone. 🚀📚

What's Changed

• Bump actions/checkout from 5 to 6 in /.github/workflows by @dependabot[bot] in #174
• Bump actions/download-artifact from 6 to 7 in /.github/workflows by @dependabot[bot] in #176
• Bump actions/upload-artifact from 5 to 6 in /.github/workflows by @dependabot[bot] in #175
• Fix race condition on GitHub authors by @glenn-jocher in #177

Full Changelog: v0.2.3...v0.2.4

v0.2.3 - Add parallel `postprocess` (#173)

🌟 Summary

v0.2.3 makes the mkdocs Ultralytics plugin faster and more robust 🚀 by adding optional parallel HTML postprocessing and a smarter, thread-safe cache for GitHub author data.

---

📊 Key Changes

• ⚙️ Parallel postprocess_site execution

  • New arguments: use_processes: bool = True and workers: int | None = None.
  • HTML files can now be processed in parallel using:
    • Multiple processes (ProcessPoolExecutor) or
    • Multiple threads (ThreadPoolExecutor), depending on use_processes.
  • Automatically picks an appropriate worker count based on CPU cores (or a user-specified workers value).

• 🧱 Shared worker state for process pools

  • Introduces _WORKER_STATE plus helper _set_worker_state and _process_file to avoid repeatedly sending large read-only data (like config and Git metadata) to each task.
  • Reduces overhead and improves performance when using process-based parallelism.

• 📈 Improved progress handling & logging

  • Uses a single global TQDM progress bar for all workers.
  • Enables logging for the single-worker (sequential) path; disables per-task logging in parallel pools to stay safe and pickle-friendly.
  • Clear console message indicating how many HTML files will be processed and with how many workers and which mode (thread or process).

• 🧵 Thread-safe, cached GitHub author lookups

  • Adds a global, shared cache:
    • _AUTHOR_CACHE, _AUTHOR_CACHE_MTIME, and _CACHE_LOCK in plugin/utils.py.
  • get_github_username_from_email:
    • Wraps cache access and updates in a lock to avoid data races when running in parallel.
    • Avoids duplicate GitHub REST API calls and redundant avatar URL resolution.
  • get_github_usernames_from_file:
    • Loads mkdocs_github_authors.yaml only once per process.
    • Tracks modification time so it can reload if the file changes.
    • Only writes the YAML file back when the cache actually changed, reducing I/O contention.

• 🛡 More robust GitHub lookup behavior

  • Safely handles:
    • Empty email strings (logs a warning when verbose).
    • GitHub noreply emails by deriving the username directly and resolving the avatar URL once.
  • Ensures cache writes are consistent and guarded by a lock.

• 🧪 Minor structural optimizations

  • Simplified markdown index (md_index) creation in postprocess_site using a dictionary comprehension.
  • Centralized common parameters into task_kwargs for cleaner worker submission logic.

---

🎯 Purpose & Impact

• 🚀 Faster documentation builds

  • Parallel processing of HTML files significantly speeds up mkdocs builds, especially for large sites with many pages.
  • Reduced overhead for Git metadata and author resolution in process pools.

• 🤝 More stable parallel execution

  • Thread-safe caching and careful locking prevent race conditions and YAML file corruption when running with multiple workers.
  • Less risk of hitting GitHub rate limits due to repeated identical API calls.

• 📉 Lower I/O and API usage

  • Only writes mkdocs_github_authors.yaml when needed.
  • Caches avatar URLs and usernames, so repeated builds or pages with the same authors don’t re-query GitHub.

• 🔧 Flexible configuration for different environments

  • workers lets you tune performance for CI, local development, or resource-constrained machines.
  • use_processes lets you choose between process-based isolation (often faster for CPU-heavy tasks) and threads (lighter-weight, easier debugging).

• 📚 Better user experience

  • Clearer progress output during postprocess_site.
  • More reliable author attribution and avatars in generated docs, with fewer intermittent failures under load.

In short: v0.2.3 focuses on performance, scalability, and robustness for documentation postprocessing, particularly when running mkdocs with parallel workers ⚡📚.

What's Changed

• Add parallel postprocess by @glenn-jocher in #173

Full Changelog: v0.2.2...v0.2.3

v0.2.2 - Single `git` call for authors and dates (#172)

🌟 Summary

v0.2.2 makes the MkDocs Ultralytics Plugin faster and more efficient by centralizing all git metadata lookups, while also improving the GitHub issue experience with structured templates and helpful links. 🚀

---

📊 Key Changes

• 🧠 Single git metadata pass for all pages (PR #172)

  • Adds MetaPlugin.on_config to compute git metadata (repo URL + git log map) once at build time.
  • Introduces build_git_map in processor.py to gather creation/modified dates and author emails for all Markdown files using a single git log command.
  • Updates get_git_info to read from cached git_data instead of running git log/git blame per file.
  • Passes git_data and repo_url into process_html and process_html_file, ensuring all HTML processing can reuse the same metadata.

• ⚙️ Faster postprocessing with progress feedback (PR #172)

  • postprocess_site now builds a shared git map for all source files before processing HTML.
  • Integrates optional TQDM progress bars (when ultralytics is installed) to show per-file progress during postprocessing.
  • Adds a pluggable log callback to process_html_file so messages can be routed through TQDM or standard output cleanly.
  • Improves error handling and logging for file read/write issues while keeping verbose output optional.

• ✍️ Smarter author resolution (PR #172)

  • get_github_usernames_from_file now uses precomputed email counts (from build_git_map) instead of running git commands itself.
  • Accepts an optional repo_url to build consistent author profile links, falling back to an Ultralytics repo URL when unavailable.
  • Reduces duplicate git calls and centralizes all git access in one place.

• 🧩 New GitHub issue templates for better collaboration (PR #171)

  • Adds structured templates for:
    • 🐛 Bug Reports
    • 🚀 Feature Requests
    • ❓ Questions
  • Provides a .github/ISSUE_TEMPLATE/config.yml with contact links to:
    • MkDocs Ultralytics Plugin README
    • PyPI package
    • Ultralytics Community Forum
    • Ultralytics Discord
  • Encourages users to search existing issues/discussions before opening new ones and optionally volunteer to submit PRs.

---

🎯 Purpose & Impact

• ⚡ Performance & scalability

  • By moving from “git per file” to a single cached git pass, large documentation sites avoid hundreds or thousands of repeated git calls.
  • Builds and postprocessing runs become noticeably faster and more stable, especially on CI or large repos.

• 🧾 Richer and more consistent metadata

  • Creation and last-modified dates, plus author information, are now computed consistently from a shared git log map.
  • JSON-LD and SEO-related features that depend on dates/authors become more reliable and easier to reason about.

• 🧹 Cleaner architecture & easier maintenance

  • All git interactions are centralized (build_git_map + git_data), reducing complexity and the risk of inconsistent behavior between plugin mode and postprocess mode.
  • Utilities like get_github_usernames_from_file are now focused purely on mapping emails to GitHub users, not running git commands.

• 👀 Better user experience during builds

  • Optional progress bars and structured logging make it easier to see what’s happening during postprocessing, especially on large sites.
  • Clearer error messages for read/write failures help diagnose broken HTML files or permission issues.

• 🤝 Smoother support and community workflows

  • Issue templates guide users to provide essential details (environment, minimal repro, motivation, context), which speeds up triage and responses.
  • Direct links to docs, PyPI, and community channels help users self-serve or get the right kind of help faster.

Overall, v0.2.2 is a performance and tooling upgrade: faster builds, cleaner git metadata handling, and better collaboration around issues and feature requests. 🎉

What's Changed

• Issue templates by @glenn-jocher in #171
• Single git call for authors and dates by @glenn-jocher in #172

Full Changelog: v0.2.1...v0.2.2

v0.2.1 - Improve meta image selection (#170)

🌟 Summary

Improved, safer social preview image selection for pages—now picks relevant images from the article body with robust fallbacks, reducing broken or unsafe previews. 🖼️✅

📊 Key Changes

• Scope-limited image scanning to the article content area for more relevant picks.
• Skips unsupported or unsafe sources (AVIF, javascript:, data:) for better compatibility and security.
• Deterministic fallback chain: first valid body image → YouTube thumbnail → default image.
• Sets meta["image"] only when a suitable source is found to avoid bad metadata.
• Version bump to 0.2.1.

Primary change authored by @glenn-jocher in PR #170: Improve meta image selection.

🎯 Purpose & Impact

• More reliable social cards and SEO previews across pages. 📣
• Fewer broken images and reduced risk from unsafe sources. 🔒
• Consistent behavior with clear fallback logic, simplifying maintenance. 🧭
• No breaking changes; site owners may want to ensure:
  • A sensible default_image is configured.
  • Page images use widely supported formats (JPG/PNG/WebP) and valid URLs.

What's Changed

• Improve meta image selection by @glenn-jocher in #170

Full Changelog: v0.2.0...v0.2.1

v0.2.0 - New `postprocess.py` standalone route (#169)

🌟 Summary

MkDocs Ultralytics Plugin v0.2.0 introduces a new standalone postprocessing route with a shared HTML processor, making Ultralytics’ SEO and social features work with any static site generator—not just MkDocs. 🚀

📊 Key Changes

• Standalone postprocess route

  • Added a new plugin/postprocess.py to process any static site output (MkDocs, Zensical, Hugo, Jekyll, etc.). PR #169 by @glenn-jocher
  • Introduced plugin/processor.py as the shared core HTML processor (meta tags, JSON-LD, Git info, social share, Copy for LLM)
  • Refactored plugin/main.py to delegate to process_html() for consistent behavior across modes
  • Exported postprocess_site in plugin/__init__.py and bumped version to 0.2.0

• Documentation and guidance

  • Revamped README with two modes: Plugin Mode (MkDocs) and Postprocess Mode (any static site), plus setup and architecture overviews. PR #169
  • README badges updated and clarified, with supported Python versions shown. PR #160 by @glenn-jocher

• Ecosystem and CI updates

  • Official Python 3.14 support declared. PR #165 by @glenn-jocher 🐍
  • Dependabot schedule tuned to weekly for faster updates (with capped open PRs). PR #168 by @glenn-jocher, diff
  • GitHub Actions updated to latest major versions:
    • actions/setup-python v6, astral-sh/setup-uv v7, actions/upload-artifact v5, actions/download-artifact v6. PRs #161, #163, #166, #167 by @dependabot

🎯 Purpose & Impact

• Broader compatibility and portability

  • Run Ultralytics’ SEO, JSON-LD, Git info, share buttons, and Copy-for-LLM features on any static site generator, not just MkDocs. 🌐
  • Easier adoption across diverse doc stacks without plugin support.

• Consistency and maintainability

  • Single shared HTML processor dramatically reduces duplication, ensuring consistent output across Plugin and Postprocess modes. 🧩
  • Simplifies future maintenance and feature rollout.

• Developer experience and reliability

  • Clearer setup and architecture documentation reduces onboarding time. 📘
  • Faster, smaller dependency updates improve CI reliability and security posture. 🔒⚡
  • Python 3.14 support expands compatibility for modern environments.

Quick start for Postprocess Mode example:

from plugin import postprocess_site

postprocess_site(
    site_dir="site",
    docs_dir="docs",
    site_url="https://example.com",
    default_image="https://example.com/image.png",
    default_author="you@example.com",
    add_desc=True,
    add_image=True,
    add_authors=True,
    add_json_ld=True,
    add_share_buttons=True,
    add_css=True,
    add_copy_llm=True,
    verbose=True,
)

Overall, v0.2.0 is a big step toward universal, consistent, and maintainable docs enhancements—wherever you build your site. ✨

What's Changed

• Update README.md with Python versions by @glenn-jocher in #160
• Bump actions/setup-python from 5 to 6 in /.github/workflows by @dependabot[bot] in #161
• Update dependabot.yml by @glenn-jocher in #162
• Bump astral-sh/setup-uv from 6 to 7 in /.github/workflows by @dependabot[bot] in #163
• Add Python 3.14 support by @glenn-jocher in #165
• Update dependabot.yml by @glenn-jocher in #168
• Bump actions/download-artifact from 5 to 6 in /.github/workflows by @dependabot[bot] in #167
• Bump actions/upload-artifact from 4 to 5 in /.github/workflows by @dependabot[bot] in #166
• New postprocess.py standalone route by @glenn-jocher in #169

Full Changelog: v0.1.30...v0.2.0

v0.1.30 - refactor: ♻️ update type hints to use built-in types for future types (#159)

🌟 Summary

v0.1.30 modernizes typing across the MkDocs plugin for cleaner, future-proof code, with no runtime changes, plus general refactors for readability and performance. ♻️✨

📊 Key Changes

• Modern Python typing overhaul (PR #159 by @onuralpszr) ✅
  • Switched from typing.Dict, List, Tuple, Optional to built-in dict, list, tuple, and X | None
  • Added from __future__ import annotations to defer type evaluation and simplify forward references
  • Streamlined type hints and cleaned unused imports across functions like get_git_info, parse_faq, and GitHub utilities
• Version bump: 0.1.29 → 0.1.30 📦
• Code quality and performance refactor (PR #158 by @pderrenger) 🚀
  • Simplified logic, removed redundancies, and improved structure

🎯 Purpose & Impact

• Improved code readability and consistency with modern Python best practices 🧠
• Better static type checking and editor tooling for contributors 🛠️
• No user-facing or behavioral changes—documentation builds remain the same ✅
• Small performance and maintainability gains from refactoring, enabling easier future enhancements 🌱

What's Changed

• Ultralytics Refactor https://ultralytics.com/actions by @pderrenger in #158
• refactor: ♻️ update type hints to use built-in types for future types by @onuralpszr in #159

Full Changelog: v0.1.29...v0.1.30

v0.1.29 - MetaPlugin fix for `beautifulsoup4>=4.13.5` (#156)

🌟 Summary

Improves MkDocs MetaPlugin compatibility and reliability by supporting beautifulsoup4>=4.13.5 and refining content insertion logic for cleaner documentation builds. 🧩📚

📊 Key Changes

• 🔧 Compatibility update: Raised dependency to beautifulsoup4>=4.13.5 (removed upper cap), ensuring the plugin works with the latest BeautifulSoup releases.
• 🩹 Logic fix: Adjusted fallback insertion from if to elif in insert_content to avoid double-inserting content when a comments header exists.
• 🏷️ Version bump: version updated to 0.1.29.

🎯 Purpose & Impact

• ✅ Smoother doc builds: Fix verified with mkdocs serve; prevents duplicate content blocks and results in cleaner pages.
• 📦 Better ecosystem compatibility: Aligns with newer BeautifulSoup versions, reducing dependency conflicts in modern environments.
• ⚠️ Action for users: You may need to upgrade BeautifulSoup to 4.13.5+.
  • Example: pip install -U beautifulsoup4
• 🔒 More stable docs pipeline: Improves reliability for teams building or extending docs with the MetaPlugin.

See the Ultralytics Docs for details.

What's Changed

• MetaPlugin fix for beautifulsoup4>=4.13.5 by @onuralpszr in #156

New Contributors

• @onuralpszr made their first contribution in #156

Full Changelog: v0.1.28...v0.1.29

v0.1.28 - Reduce `requests>=2.28.1` (#154)

🌟 Summary

v0.1.28 is a safe maintenance release focused on dependency compatibility and CI reliability—no behavioral changes to the plugin itself. ✅

📊 Key Changes

• Lowered minimum requests dependency to >=2.28.1 to align with Ultralytics’ stack and avoid conflicts (#154 by @glenn-jocher). 🔧
• Bumped plugin version to 0.1.28. 🏷️
• CI hardening for SBOM generation: use a dedicated uv virtual env and editable install; standardize on VIRTUAL_ENV (#148, #150 by @glenn-jocher). 🧪
• Upgraded GitHub Actions checkout to v5 for newer runner compatibility (#153 by @dependabot[bot]). ⬆️
• README badge link updated to ClickPy. 📈
• Internal refactor improvements with no user-facing behavior changes (#151 by @pderrenger). 🧹
• One no-op housekeeping PR (#149). 🗒️

🎯 Purpose & Impact

• Broader environment support: allows slightly older requests versions, reducing dependency conflicts across Ultralytics projects. 🌍
• Stable and predictable docs builds: improved SBOM workflow boosts reliability and speeds up CI. ⚡
• No code path changes in the plugin: safe to upgrade with minimal risk for all users. 🛡️
• Modernized CI tooling (checkout v5) ensures compatibility with current GitHub runners. 🔄

Tip: You can upgrade with pip install -U mkdocs-ultralytics-plugin.

What's Changed

• SBOM uv sync fix by @glenn-jocher in #148
• SBOM uv sync fix by @glenn-jocher in #149
• Update publish.yml by @glenn-jocher in #150
• Ultralytics Refactor https://ultralytics.com/actions by @pderrenger in #151
• Bump actions/checkout from 4 to 5 in /.github/workflows by @dependabot[bot] in #153
• Reduce requests>=2.28.1 by @glenn-jocher in #154

Full Changelog: v0.1.27...v0.1.28

v0.1.27 - Add automated SPDX SBOM generation to releases (#147)

🌟 Summary

Automated security and release reliability upgrade: v0.1.27 adds SPDX SBOM generation and safer release notifications, plus workflow updates and a version bump. 🔐🚀

📊 Key Changes

• 🔐 Automatic SBOM creation: Generates an SPDX JSON SBOM using Anchore after successful build/publish.
• 📦 Release attachment: SBOM is uploaded to each GitHub Release tag for easy access.
• 🛡️ Safer notifications: Escapes quotes in PR titles to prevent CI parsing failures.
• ⚙️ Workflow update: actions/download-artifact upgraded from v4 → v5 for improved artifact handling.
• 🔖 Version bump: Plugin version updated to 0.1.27.

🎯 Purpose & Impact

• ✅ Transparency & compliance: SBOMs provide a clear inventory of dependencies, supporting audits and security reviews.
• 🔍 Better security tooling: Enables automated scanners to verify components in every release.
• 🧱 More reliable CI: Quote-escaping reduces flaky release notifications caused by special characters.
• 📈 Smoother releases: Automates security-focused artifacts and keeps workflows current, improving trust and maintainability.

What's Changed

• Bump actions/download-artifact from 4 to 5 in /.github/workflows by @dependabot[bot] in #146
• Add automated SPDX SBOM generation to releases by @glenn-jocher in #147

Full Changelog: v0.1.26...v0.1.27

v0.1.26 - Fix author profile image links (#145)

🌟 Summary

Improved author avatar image handling in the Ultralytics MkDocs plugin for more reliable and consistent display. 🖼️✨

📊 Key Changes

• Updated the plugin version to 0.1.26.
• Enhanced the way author profile image URLs are built, ensuring the correct image size parameter is always included, no matter how the URL is formatted.

🎯 Purpose & Impact

• Guarantees author avatars appear correctly and consistently across documentation pages.
• Prevents issues where profile images might not load due to incorrect URL formatting.
• Delivers a smoother, more polished experience for anyone viewing documentation with author information.

What's Changed

• Fix author profile image links by @glenn-jocher in #145

Full Changelog: v0.1.25...v0.1.26