{"author":null,"author_email":"Glenn Jocher ","bugtrack_url":null,"classifiers":["Development Status :: 4 - Beta","Intended Audience :: Developers","Intended Audience :: Education","Intended Audience :: Science/Research","License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)","Operating System :: MacOS","Operating System :: Microsoft :: Windows","Operating System :: POSIX :: Linux","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering","Topic :: Scientific/Engineering :: Artificial Intelligence","Topic :: Software Development"],"description":" $\"Ultralytics$ \n\n# 🚀 MkDocs Ultralytics Plugin\n\nWelcome to the documentation for the MkDocs Ultralytics Plugin! 📄 This powerful plugin enhances your [MkDocs](https://www.mkdocs.org/)-generated 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 Markdown project's visibility on the web.\n\n[![PyPI version](https://badge.fury.io/py/mkdocs-ultralytics-plugin.svg)](https://badge.fury.io/py/mkdocs-ultralytics-plugin)\n[![Downloads](https://static.pepy.tech/badge/mkdocs-ultralytics-plugin)](https://www.pepy.tech/projects/mkdocs-ultralytics-plugin)\n[![Ultralytics Actions](https://github.com/ultralytics/mkdocs/actions/workflows/format.yml/badge.svg)](https://github.com/ultralytics/mkdocs/actions/workflows/format.yml)\n[![Ultralytics Discord](https://img.shields.io/discord/1089800235347353640?logo=discord&logoColor=white&label=Discord&color=blue)](https://discord.com/invite/ultralytics)\n[![Ultralytics Forums](https://img.shields.io/discourse/users?server=https%3A%2F%2Fcommunity.ultralytics.com&logo=discourse&label=Forums&color=blue)](https://community.ultralytics.com/)\n[![Ultralytics Reddit](https://img.shields.io/reddit/subreddit-subscribers/ultralytics?style=flat&logo=reddit&logoColor=white&label=Reddit&color=blue)](https://reddit.com/r/ultralytics)\n\n## ✨ Features\n\nThis plugin seamlessly integrates a variety of valuable features into your MkDocs site:\n\n- **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.\n- **Keyword Customization**: Allows you to define specific meta keywords directly within your Markdown front matter for targeted SEO.\n- **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.\n- **Simple Sharing**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content, encouraging readers to share.\n- **Git Insights**: Gathers and displays [Git](https://git-scm.com/) commit information, including update dates and authors, directly within the page footer for transparency.\n- **JSON-LD Support**: Adds structured data in JSON-LD format, helping search engines understand your content better and potentially enabling rich results.\n- **FAQ Parsing**: Automatically parses FAQ sections (if present) and includes them in the structured data for enhanced search visibility.\n- **Customizable Styling**: Includes optional inline CSS to maintain consistent styling for plugin elements across your documentation, aligning with themes like [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).\n\n## 🛠️ Installation\n\nGetting started with the MkDocs Ultralytics Plugin is straightforward. Install it via [pip](https://pypi.org/project/pip/) using the following command:\n\n```bash\npip install mkdocs-ultralytics-plugin\n```\n\n## 💻 Usage\n\nTo activate the plugin within your MkDocs project, add it to the `plugins` section of your `mkdocs.yml` configuration file:\n\n```yaml\nplugins:\n - mkdocstrings # Example of another plugin\n - search # Example of another plugin\n - ultralytics # Add the Ultralytics plugin here\n```\n\n## ⚙️ Configuration Arguments\n\nThe plugin offers several configuration arguments to customize its behavior according to your project's requirements:\n\n- `verbose` (bool): Enables or disables detailed console output during the build process. Useful for debugging. Default: `True`.\n- `enabled` (bool): Globally enables or disables the plugin. Default: `True`.\n- `default_image` (str | None): Specifies a fallback image URL to use for meta tags if no image is found within the page content. Default: `None`.\n- `default_author` (str | None): Sets a default GitHub author email to use if Git author information cannot be retrieved for a page. Default: `None`.\n- `add_desc` (bool): Controls whether meta description tags are automatically generated. Default: `True`.\n- `add_image` (bool): Controls whether meta image tags (Open Graph, Twitter) are automatically generated. Default: `True`.\n- `add_keywords` (bool): Controls whether meta keyword tags are generated based on front matter. Default: `True`.\n- `add_share_buttons` (bool): Determines if social media share buttons (Twitter, LinkedIn) are added to the page content. Default: `True`.\n- `add_authors` (bool): Controls the display of author and last updated date information in the content footer based on Git history. Default: `False`.\n- `add_json_ld` (bool): Enables the generation and injection of JSON-LD structured data into the page's head. Default: `False`.\n- `add_css` (bool): Determines if the plugin's inline CSS styles are included for elements like share buttons. Default: `True`.\n\nYou can include these arguments under the `ultralytics` entry in your `mkdocs.yml` file like this:\n\n```yaml\nplugins:\n - mkdocstrings\n - search\n - ultralytics:\n verbose: True\n enabled: True\n default_image: \"https://www.ultralytics.com/images/social.png\" # Example default image\n default_author: \"git@ultralytics.com\" # Example default author\n add_desc: True\n add_image: True\n add_keywords: True\n add_share_buttons: True\n add_authors: False # Disabled by default\n add_json_ld: False # Disabled by default\n add_css: True\n```\n\n## 🧩 How It Works\n\nHere’s a brief overview of the plugin's core functionalities:\n\n### Meta Description Generation\n\nWhen `add_desc` is enabled, the plugin extracts the first paragraph from your Markdown content and uses it to generate a `` tag within the `` section of the corresponding HTML page. This helps search engines and users understand the page's content at a glance.\n\n### Meta Image Tagging\n\nIf `add_image` is active, the plugin identifies the first image referenced in the Markdown source. This image URL is then used to populate the `` and `` tags. If no image is detected on the page, the URL provided in `default_image` (if set) is used as a fallback.\n\n### Meta Keyword Integration\n\nBy defining keywords in the Markdown front matter (e.g., `keywords: machine learning, computer vision, mkdocs`), and with `add_keywords` enabled, the plugin injects a corresponding `` tag into the page's ``.\n\n### Social Share Buttons\n\nActivating `add_share_buttons` automatically appends pre-styled Twitter and LinkedIn sharing buttons to the bottom of your main content area, making it easy for readers to share your documentation.\n\n### Git Information Display\n\nWhen `add_authors` is enabled, the plugin leverages Git history to retrieve the commit timestamp and author(s) for each page. This information is then displayed at the bottom of the page, providing context on when the content was last updated and by whom.\n\n## 💡 Plugin Code Insight\n\nThe core logic resides within the `MetaPlugin` class in `plugin.py`. This class hooks into the MkDocs build process to modify page content and metadata.\n\n```python\n# Import the base class for MkDocs plugins\nfrom mkdocs.plugins import BasePlugin\n\n\n# Define the MetaPlugin class inheriting from BasePlugin\nclass MetaPlugin(BasePlugin):\n # This method runs after the Markdown is converted to HTML,\n # but before the template is rendered.\n # It's used here primarily to extract information like the first paragraph or image.\n def on_page_content(self, content, page, config, files):\n # Logic to find the first paragraph for meta description\n # Logic to find the first image for meta image tags\n # ... (details omitted for brevity)\n # The modified or extracted data is often stored for later use.\n return content # Return the original content, as modifications happen later\n\n # This method runs after the page template has been rendered.\n # It allows modification of the final HTML output.\n def on_post_page(self, output, page, config):\n # Logic to inject generated meta tags (description, image, keywords) into \n # Logic to add share buttons HTML to the end of the content area\n # Logic to add author/date footer HTML\n # Logic to add JSON-LD script tag to \n # Logic to add inline CSS if enabled\n # ... (details omitted for brevity)\n return output # Return the modified HTML output\n```\n\nThis structure allows the plugin to analyze content and then inject the necessary HTML elements and metadata into the final output effectively. Check the source code for the full implementation details.\n\n## 🤝 Contribute\n\nCollaboration fuels innovation! 🤗 The success of Ultralytics' open-source projects, including this plugin, thrives on community contributions. We welcome your involvement, whether it's fixing bugs, proposing new features, improving documentation, engaging in discussions, or sharing how you use Ultralytics tools.\n\nPlease see our [Contributing Guide](https://docs.ultralytics.com/help/contributing/) for more details on how you can make a difference. Filling out our short [Survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey) also provides valuable feedback. We sincerely appreciate 🙇‍♂️ every contribution!\n\n[![Ultralytics open-source contributors](https://raw.githubusercontent.com/ultralytics/assets/main/im/image-contributors.png)](https://github.com/ultralytics/ultralytics/graphs/contributors)\n\n## 📜 License\n\nUltralytics provides two licensing options to accommodate different use cases:\n\n- **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.\n- **Enterprise License**: Designed for commercial applications, this license allows seamless integration of Ultralytics software and AI models into commercial products and services, bypassing the open-source requirements of AGPL-3.0. If your project requires an Enterprise License, please visit [Ultralytics Licensing](https://www.ultralytics.com/license).\n\n## ✉️ Connect with Us\n\nEncountered a bug or have an idea for a new feature? Please visit [GitHub Issues](https://github.com/ultralytics/mkdocs/issues) to report problems or suggest enhancements. For broader discussions, questions, and community support related to Ultralytics projects, join our vibrant [Discord](https://discord.com/invite/ultralytics) server and check out the [Ultralytics Reddit](https://www.reddit.com/r/ultralytics/?rdt=34950).\n\n
\n

\n $\"Ultralytics$ \n $\"space\"$ \n $\"Ultralytics$ \n $\"space\"$ \n $\"Ultralytics$ \n $\"space\"$ \n $\"Ultralytics$ \n $\"space\"$ \n $\"Ultralytics$ \n $\"space\"$ \n $\"Ultralytics$ \n $\"space\"$ \n $\"Ultralytics$ \n

\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":["License-File"],"home_page":null,"keywords":"Ultralytics, Docs, MkDocs, Plugin","license":"AGPL-3.0","license_expression":null,"license_files":["LICENSE"],"maintainer":null,"maintainer_email":"Ultralytics ","name":"mkdocs-ultralytics-plugin","package_url":"https://pypi.org/project/mkdocs-ultralytics-plugin/","platform":null,"project_url":"https://pypi.org/project/mkdocs-ultralytics-plugin/","project_urls":{"Bug Reports":"https://github.com/ultralytics/mkdocs/issues","Changelog":"https://github.com/ultralytics/mkdocs/releases","Documentation":"https://docs.ultralytics.com","Homepage":"https://ultralytics.com","Source":"https://github.com/ultralytics/mkdocs"},"provides_extra":["dev"],"release_url":"https://pypi.org/project/mkdocs-ultralytics-plugin/0.1.19/","requires_dist":["mkdocs>=1.0","beautifulsoup4<=4.12.3,>=4.9.3","pyyaml","requests>=2.31.0","pytest; extra == \"dev\""],"requires_python":">=3.8","summary":"An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.","version":"0.1.19","yanked":false,"yanked_reason":null}

Dependency	Optional
beautifulsoup4	false
mkdocs	false
pyyaml	false
requests	false
pytest	true

Package search

mkdocs-ultralytics-plugin

project_urls

Dependencies

All package metadata

Releases