An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
Project description
🚀 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.
🌟 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 with the following command:
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:
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:
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:
# 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 how you can be part of the journey. Filling out our survey is another great way to share your feedback. We are deeply thankful 🙇♂️ for each contributor's time and efforts!
📜 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 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 options.
✉️ Connect with Us
Have you stumbled upon a glitch, or do you have a splendid feature idea? Pop over to GitHub Issues to drop us a line! Also, join our Discord and Reddit for buzzing discussions, insights, and tips around our shared ML journeys.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mkdocs_ultralytics_plugin-0.1.9.tar.gz.
File metadata
- Download URL: mkdocs_ultralytics_plugin-0.1.9.tar.gz
- Upload date:
- Size: 26.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | df28b41759e598fd0cba9f8a592c767fa2d9ca231e7d51323b7631fd959328d6 |
|
| MD5 | 9d5e41f7699f110cac294aeb98fee140 |
|
| BLAKE2b-256 | ba08133ab6b76981a3874f74ba05b06e6366fb323e75c74b7a1239bff7edba5b |
File details
Details for the file mkdocs_ultralytics_plugin-0.1.9-py3-none-any.whl.
File metadata
- Download URL: mkdocs_ultralytics_plugin-0.1.9-py3-none-any.whl
- Upload date:
- Size: 26.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | b6242206e368f6c0d2ae74ab1a1ed6da4327689766803574a0aa498dd6378d96 |
|
| MD5 | 9b0145b874f41ba679d37bf2b8e1e106 |
|
| BLAKE2b-256 | 8fcd1b99cfde5b326af18c0c2c8ee079eed3c966c8e0d98510d3275c6c08f2be |
