🚀 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.

Oven