<a href="https://www.ultralytics.com/" target="_blank"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg" width="320" alt="Ultralytics logo"></a>
# 🚀 MkDocs Ultralytics Plugin
Welcome to the MkDocs Ultralytics Plugin documentation! 📄 This powerful plugin enhances your MkDocs-generated documentation with advanced SEO optimizations, interactive social elements, and structured data support. It automates the generation of meta tags, incorporates social sharing features, and adds JSON-LD structured data to elevate user engagement and improve your Markdown project's visibility on the web.
[](https://badge.fury.io/py/mkdocs-ultralytics-plugin) [](https://www.pepy.tech/projects/mkdocs-ultralytics-plugin) [](https://github.com/ultralytics/mkdocs/actions/workflows/format.yml) <a href="https://discord.com/invite/ultralytics"><img alt="Discord" src="https://img.shields.io/discord/1089800235347353640?logo=discord&logoColor=white&label=Discord&color=blue"></a> <a href="https://community.ultralytics.com/"><img alt="Ultralytics Forums" src="https://img.shields.io/discourse/users?server=https%3A%2F%2Fcommunity.ultralytics.com&logo=discourse&label=Forums&color=blue"></a> <a href="https://reddit.com/r/ultralytics"><img alt="Ultralytics Reddit" src="https://img.shields.io/reddit/subreddit-subscribers/ultralytics?style=flat&logo=reddit&logoColor=white&label=Reddit&color=blue"></a>
## 🌟 Features
This plugin seamlessly integrates a variety of features into your MkDocs site:
- **Meta Tag Generation**: Creates meta description and image tags from the first paragraph and image on the page.
- **Keyword Customization**: Allows you to define meta keywords directly in your Markdown front matter.
- **Social Media Optimization**: Generates Open Graph and Twitter meta tags for improved sharing on social platforms.
- **Sharing Made Simple**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content.
- **Git Insights**: Gathers and displays git commit information, including dates and authors, within the page footer.
- **JSON-LD Support**: Adds structured data in JSON-LD format for better search engine integration.
- **FAQ Parsing**: Automatically parses FAQ sections and includes them in the structured data.
- **Customizable Styling**: Includes inline CSS for consistent styling across your documentation.
## 🛠 Installation
Getting started with the MkDocs Ultralytics Plugin is easy! Install it via [pip](https://pypi.org/project/mkdocs-ultralytics-plugin/) with the following command:
```bash
pip install mkdocs-ultralytics-plugin
```
## 💻 Usage
To enable the plugin in your MkDocs configuration, simply add it under the `plugins` section in your `mkdocs.yml` file:
```yaml
plugins:
- mkdocstrings
- search
- ultralytics
```
## ⚙️ Plugin Arguments
The plugin supports several configuration arguments to tailor its behavior to your needs:
- `verbose`: Toggles verbose output. Useful for debugging. (default: `True`)
- `enabled`: Toggles plugin activation. (default: `True`)
- `default_image`: Provides a fallback image URL if none is found in your content. (default: `None`)
- `add_desc`: Controls the generation of meta description tags. (default: `True`)
- `add_image`: Manages meta image tag generation. (default: `True`)
- `add_keywords`: Allows meta keyword tag generation. (default: `True`)
- `add_share_buttons`: Adds or removes social share buttons. (default: `True`)
- `add_authors`: Includes author and updated date information in the content footer. (default: `False`)
- `add_json_ld`: Adds JSON-LD structured data to the page. (default: `False`)
- `add_css`: Includes inline CSS for styling. (default: `True`)
Include these arguments under the `ultralytics` plugin entry in your `mkdocs.yml`:
```yaml
plugins:
- mkdocstrings
- search
- ultralytics:
verbose: True
enabled: True
default_image: "https://example.com/default-image.png"
add_desc: True
add_image: True
add_keywords: True
add_share_buttons: True
add_authors: False
add_json_ld: False
add_css: True
```
## 🧩 How it works
Here's a breakdown of the plugin's inner workings:
### Meta Description
When `add_desc` is on, the plugin plucks the first paragraph from your Markdown and turns it into a `<meta name="description">` tag within the `<head>` of your page.
### Meta Image
Enabled by `add_image`, the first available image in the Markdown is assigned as `<meta property="og:image">` and `<meta property="twitter:image">` tags. If no image is detected, `default_image` steps in.
### Meta Keywords
Manually specify meta keywords in the Markdown front matter to inject a `<meta name="keywords">` tag into the `<head>` of your page.
### Share Buttons
Engage `add_share_buttons`, and voila! Twitter and LinkedIn sharing buttons appear, inviting users to spread the word about your content.
### Git Dates and Authors
With `add_dates` and `add_authors`, the plugin fetches and flaunts the git commit timestamp and author names at the bottom of your page, keeping readers informed.
## 💡 Plugin Code Insight
The `MetaPlugin` class within `plugin.py` is the heart of the plugin, orchestrating the metadata and feature insertions:
```python
# Our MkDocs plugin inherits features from the BasePlugin available in mkdocs
from mkdocs.plugins import BasePlugin
# The MetaPlugin class holds the core functionality
class MetaPlugin(BasePlugin):
# Acts on the page content to generate meta tags
def on_page_content(self, content, page, config, files):
# ... (omitted code handling meta description and image generation)
# Comments could further explain code (but are omitted for brevity)
return content
# Alters the final page output to include the new meta tags
def on_post_page(self, output, page, config):
# ... (omitted code that injects generated meta tags into the output)
# Additional comments could describe processing steps
return output
```
## 🤝 Contribute
Join in on the collaboration! 🤗 The success of Ultralytics' open-source initiatives springs from the vibrant contributions of our community. Whether you're fixing bugs, adding features, warming up our discussions, or sharing your Ultralytics project tale, [check out](https://docs.ultralytics.com/help/contributing/) how you can be part of the journey. Filling out our [survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey) is another great way to share your feedback. We are deeply thankful 🙇♂️ for each contributor's time and efforts!
<!-- A visual tribute to our contributors! -->
<a href="https://github.com/ultralytics/yolov5/graphs/contributors">
<img width="100%" src="https://github.com/ultralytics/assets/raw/main/im/image-contributors.png" alt="Ultralytics open-source contributors"></a>
## 📜 License
Ultralytics projects come with two licensing flavors:
- **AGPL-3.0 License**: This license fosters open collaboration and knowledge sharing, making it a perfect match for students and hobbyists. For specifics, check the [LICENSE](https://github.com/ultralytics/ultralytics/blob/main/LICENSE) file.
- **Enterprise License**: When it comes to commercial endeavors, this license gets things rolling by allowing Ultralytics software and AI models to be woven into your business offerings without the AGPL-3.0's open-source constraints. For commercial integrations, please explore our [Ultralytics Licensing](https://www.ultralytics.com/license) options.
## ✉️ Connect with Us
Have you stumbled upon a glitch, or do you have a splendid feature idea? Pop over to [GitHub Issues](https://github.com/ultralytics/mkdocs/issues) to drop us a line! Also, join our [Discord](https://discord.com/invite/ultralytics) and [Reddit](https://www.reddit.com/r/ultralytics/) for buzzing discussions, insights, and tips around our shared ML journeys.
<br>
<div align="center">
<a href="https://github.com/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-github.png" width="3%" alt="Ultralytics GitHub"></a>
<img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
<a href="https://www.linkedin.com/company/ultralytics/"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-linkedin.png" width="3%" alt="Ultralytics LinkedIn"></a>
<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>
<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">
<a href="https://ultralytics.com/bilibili"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-bilibili.png" width="3%" alt="Ultralytics BiliBili"></a>
<img src="https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png" width="3%" alt="space">
<a href="https://discord.com/invite/ultralytics"><img src="https://github.com/ultralytics/assets/raw/main/social/logo-social-discord.png" width="3%" alt="Ultralytics Discord"></a>
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-ultralytics-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Ultralytics <hello@ultralytics.com>",
"keywords": "Ultralytics, Docs, MkDocs, Plugin",
"author": null,
"author_email": "Glenn Jocher <hello@ultralytics.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/2d/fa057ed6b3da43011655c174d52c4c0b2a15574af0a7ba77e95862cb3f93/mkdocs_ultralytics_plugin-0.1.14.tar.gz",
"platform": null,
"description": "<a href=\"https://www.ultralytics.com/\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg\" width=\"320\" alt=\"Ultralytics logo\"></a>\n\n# \ud83d\ude80 MkDocs Ultralytics Plugin\n\nWelcome to the MkDocs Ultralytics Plugin documentation! \ud83d\udcc4 This powerful plugin enhances your MkDocs-generated documentation with advanced SEO optimizations, interactive social elements, and structured data support. It automates the generation of meta tags, incorporates social sharing features, and adds JSON-LD structured data to elevate user engagement and improve your Markdown project's visibility on the web.\n\n[](https://badge.fury.io/py/mkdocs-ultralytics-plugin) [](https://www.pepy.tech/projects/mkdocs-ultralytics-plugin) [](https://github.com/ultralytics/mkdocs/actions/workflows/format.yml) <a href=\"https://discord.com/invite/ultralytics\"><img alt=\"Discord\" src=\"https://img.shields.io/discord/1089800235347353640?logo=discord&logoColor=white&label=Discord&color=blue\"></a> <a href=\"https://community.ultralytics.com/\"><img alt=\"Ultralytics Forums\" src=\"https://img.shields.io/discourse/users?server=https%3A%2F%2Fcommunity.ultralytics.com&logo=discourse&label=Forums&color=blue\"></a> <a href=\"https://reddit.com/r/ultralytics\"><img alt=\"Ultralytics Reddit\" src=\"https://img.shields.io/reddit/subreddit-subscribers/ultralytics?style=flat&logo=reddit&logoColor=white&label=Reddit&color=blue\"></a>\n\n## \ud83c\udf1f Features\n\nThis plugin seamlessly integrates a variety of features into your MkDocs site:\n\n- **Meta Tag Generation**: Creates meta description and image tags from the first paragraph and image on the page.\n- **Keyword Customization**: Allows you to define meta keywords directly in your Markdown front matter.\n- **Social Media Optimization**: Generates Open Graph and Twitter meta tags for improved sharing on social platforms.\n- **Sharing Made Simple**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content.\n- **Git Insights**: Gathers and displays git commit information, including dates and authors, within the page footer.\n- **JSON-LD Support**: Adds structured data in JSON-LD format for better search engine integration.\n- **FAQ Parsing**: Automatically parses FAQ sections and includes them in the structured data.\n- **Customizable Styling**: Includes inline CSS for consistent styling across your documentation.\n\n## \ud83d\udee0 Installation\n\nGetting started with the MkDocs Ultralytics Plugin is easy! Install it via [pip](https://pypi.org/project/mkdocs-ultralytics-plugin/) with the following command:\n\n```bash\npip install mkdocs-ultralytics-plugin\n```\n\n## \ud83d\udcbb Usage\n\nTo enable the plugin in your MkDocs configuration, simply add it under the `plugins` section in your `mkdocs.yml` file:\n\n```yaml\nplugins:\n - mkdocstrings\n - search\n - ultralytics\n```\n\n## \u2699\ufe0f Plugin Arguments\n\nThe plugin supports several configuration arguments to tailor its behavior to your needs:\n\n- `verbose`: Toggles verbose output. Useful for debugging. (default: `True`)\n- `enabled`: Toggles plugin activation. (default: `True`)\n- `default_image`: Provides a fallback image URL if none is found in your content. (default: `None`)\n- `add_desc`: Controls the generation of meta description tags. (default: `True`)\n- `add_image`: Manages meta image tag generation. (default: `True`)\n- `add_keywords`: Allows meta keyword tag generation. (default: `True`)\n- `add_share_buttons`: Adds or removes social share buttons. (default: `True`)\n- `add_authors`: Includes author and updated date information in the content footer. (default: `False`)\n- `add_json_ld`: Adds JSON-LD structured data to the page. (default: `False`)\n- `add_css`: Includes inline CSS for styling. (default: `True`)\n\nInclude these arguments under the `ultralytics` plugin entry in your `mkdocs.yml`:\n\n```yaml\nplugins:\n - mkdocstrings\n - search\n - ultralytics:\n verbose: True\n enabled: True\n default_image: \"https://example.com/default-image.png\"\n add_desc: True\n add_image: True\n add_keywords: True\n add_share_buttons: True\n add_authors: False\n add_json_ld: False\n add_css: True\n```\n\n## \ud83e\udde9 How it works\n\nHere's a breakdown of the plugin's inner workings:\n\n### Meta Description\n\nWhen `add_desc` is on, the plugin plucks the first paragraph from your Markdown and turns it into a `<meta name=\"description\">` tag within the `<head>` of your page.\n\n### Meta Image\n\nEnabled by `add_image`, the first available image in the Markdown is assigned as `<meta property=\"og:image\">` and `<meta property=\"twitter:image\">` tags. If no image is detected, `default_image` steps in.\n\n### Meta Keywords\n\nManually specify meta keywords in the Markdown front matter to inject a `<meta name=\"keywords\">` tag into the `<head>` of your page.\n\n### Share Buttons\n\nEngage `add_share_buttons`, and voila! Twitter and LinkedIn sharing buttons appear, inviting users to spread the word about your content.\n\n### Git Dates and Authors\n\nWith `add_dates` and `add_authors`, the plugin fetches and flaunts the git commit timestamp and author names at the bottom of your page, keeping readers informed.\n\n## \ud83d\udca1 Plugin Code Insight\n\nThe `MetaPlugin` class within `plugin.py` is the heart of the plugin, orchestrating the metadata and feature insertions:\n\n```python\n# Our MkDocs plugin inherits features from the BasePlugin available in mkdocs\nfrom mkdocs.plugins import BasePlugin\n\n\n# The MetaPlugin class holds the core functionality\nclass MetaPlugin(BasePlugin):\n # Acts on the page content to generate meta tags\n def on_page_content(self, content, page, config, files):\n # ... (omitted code handling meta description and image generation)\n # Comments could further explain code (but are omitted for brevity)\n return content\n\n # Alters the final page output to include the new meta tags\n def on_post_page(self, output, page, config):\n # ... (omitted code that injects generated meta tags into the output)\n # Additional comments could describe processing steps\n return output\n```\n\n## \ud83e\udd1d Contribute\n\nJoin in on the collaboration! \ud83e\udd17 The success of Ultralytics' open-source initiatives springs from the vibrant contributions of our community. Whether you're fixing bugs, adding features, warming up our discussions, or sharing your Ultralytics project tale, [check out](https://docs.ultralytics.com/help/contributing/) how you can be part of the journey. Filling out our [survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey) is another great way to share your feedback. We are deeply thankful \ud83d\ude47\u200d\u2642\ufe0f for each contributor's time and efforts!\n\n<!-- A visual tribute to our contributors! -->\n\n<a href=\"https://github.com/ultralytics/yolov5/graphs/contributors\">\n<img width=\"100%\" src=\"https://github.com/ultralytics/assets/raw/main/im/image-contributors.png\" alt=\"Ultralytics open-source contributors\"></a>\n\n## \ud83d\udcdc License\n\nUltralytics projects come with two licensing flavors:\n\n- **AGPL-3.0 License**: This license fosters open collaboration and knowledge sharing, making it a perfect match for students and hobbyists. For specifics, check the [LICENSE](https://github.com/ultralytics/ultralytics/blob/main/LICENSE) file.\n- **Enterprise License**: When it comes to commercial endeavors, this license gets things rolling by allowing Ultralytics software and AI models to be woven into your business offerings without the AGPL-3.0's open-source constraints. For commercial integrations, please explore our [Ultralytics Licensing](https://www.ultralytics.com/license) options.\n\n## \u2709\ufe0f Connect with Us\n\nHave you stumbled upon a glitch, or do you have a splendid feature idea? Pop over to [GitHub Issues](https://github.com/ultralytics/mkdocs/issues) to drop us a line! Also, join our [Discord](https://discord.com/invite/ultralytics) and [Reddit](https://www.reddit.com/r/ultralytics/) for buzzing discussions, insights, and tips around our shared ML journeys.\n\n<br>\n<div align=\"center\">\n <a href=\"https://github.com/ultralytics\"><img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-github.png\" width=\"3%\" alt=\"Ultralytics GitHub\"></a>\n <img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\">\n <a href=\"https://www.linkedin.com/company/ultralytics/\"><img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-linkedin.png\" width=\"3%\" alt=\"Ultralytics LinkedIn\"></a>\n <img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\">\n <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>\n <img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\">\n <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>\n <img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\">\n <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>\n <img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\">\n <a href=\"https://ultralytics.com/bilibili\"><img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-bilibili.png\" width=\"3%\" alt=\"Ultralytics BiliBili\"></a>\n <img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-transparent.png\" width=\"3%\" alt=\"space\">\n <a href=\"https://discord.com/invite/ultralytics\"><img src=\"https://github.com/ultralytics/assets/raw/main/social/logo-social-discord.png\" width=\"3%\" alt=\"Ultralytics Discord\"></a>\n</div>\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.",
"version": "0.1.14",
"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"
},
"split_keywords": [
"ultralytics",
" docs",
" mkdocs",
" plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "735f6aad4ccf694b92d3f4c14aed4e39879dcaa223e7a3849684875c30fca164",
"md5": "3f31be10a3b0336fd0eb9e422b4a2d29",
"sha256": "f781196ec946a28676f1e0e17dad67959b2c4fa115f13af61213e75f179359eb"
},
"downloads": -1,
"filename": "mkdocs_ultralytics_plugin-0.1.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f31be10a3b0336fd0eb9e422b4a2d29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26732,
"upload_time": "2024-11-19T09:36:45",
"upload_time_iso_8601": "2024-11-19T09:36:45.796096Z",
"url": "https://files.pythonhosted.org/packages/73/5f/6aad4ccf694b92d3f4c14aed4e39879dcaa223e7a3849684875c30fca164/mkdocs_ultralytics_plugin-0.1.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a02dfa057ed6b3da43011655c174d52c4c0b2a15574af0a7ba77e95862cb3f93",
"md5": "aed0a863fd415728e51c3e0dc376f95a",
"sha256": "89aaae6c774025d4d7d8c6151a6f9bcdd7c0e2bb2bd5aea2e3ef8973992cd4b8"
},
"downloads": -1,
"filename": "mkdocs_ultralytics_plugin-0.1.14.tar.gz",
"has_sig": false,
"md5_digest": "aed0a863fd415728e51c3e0dc376f95a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26376,
"upload_time": "2024-11-19T09:36:48",
"upload_time_iso_8601": "2024-11-19T09:36:48.252237Z",
"url": "https://files.pythonhosted.org/packages/a0/2d/fa057ed6b3da43011655c174d52c4c0b2a15574af0a7ba77e95862cb3f93/mkdocs_ultralytics_plugin-0.1.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 09:36:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ultralytics",
"github_project": "mkdocs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-ultralytics-plugin"
}
JSON
