🚀 MkDocs Ultralytics Plugin

Welcome to the MkDocs Ultralytics Plugin! 📄 This powerful tool enhances your MkDocs, Zensical, or any static site 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 structured data to elevate user engagement and improve your documentation's visibility on the web.

Two modes available:

🔌 Plugin Mode: Real-time processing during MkDocs builds
🔄 Postprocess Mode: Process any generated static site HTML after build

✨ Features

This tool seamlessly integrates valuable features into your documentation site:

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.
Keyword Customization: Allows you to define specific meta keywords directly within your Markdown front matter for targeted SEO.
Social Media Optimization: Generates Open Graph and Twitter Card meta tags to ensure your content looks great when shared on social platforms.
Simple Sharing: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content, encouraging readers to share.
Git Insights: Gathers and displays Git commit information, including update dates and authors, directly within the page footer for transparency.
JSON-LD Support: Adds structured data in JSON-LD format, helping search engines understand your content better and potentially enabling rich results.
FAQ Parsing: Automatically parses FAQ sections (if present) and includes them in the structured data for enhanced search visibility.
Copy for LLM: Adds a button to copy page content in Markdown format, optimized for sharing with AI assistants.
LLMs.txt Generation: Generates an llms.txt index after builds for LLM-friendly site discovery.
Customizable Styling: Includes optional inline CSS to maintain consistent styling across your documentation, aligning with themes like MkDocs Material.

🛠️ Installation

Install via pip:

pip install mkdocs-ultralytics-plugin

Or install from source for development:

git clone https://github.com/ultralytics/mkdocs
cd mkdocs
pip install -e .

💻 Usage

🔌 Plugin Mode (MkDocs)

Activate the plugin in your mkdocs.yml:

plugins:
  - search
  - ultralytics:
      add_desc: False
      add_image: True
      add_authors: True
      add_json_ld: True
      add_share_buttons: True
      default_image: https://example.com/image.png
      default_author: you@example.com

Then build normally:

mkdocs build
mkdocs serve

🔄 Postprocess Mode (Zensical, Hugo, Jekyll, etc.)

For static site generators that don't support MkDocs plugins, use the standalone postprocess script.

Step 1: Create postprocess.py in your project root:

from plugin import postprocess_site

if __name__ == "__main__":
    postprocess_site(
        site_dir="site",  # Your build output directory
        docs_dir="docs",  # Your source docs directory
        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,
    )

Step 2: Build your site and run postprocess:

# For Zensical
zensical build && python postprocess.py

# For MkDocs (without plugin)
mkdocs build && python postprocess.py

# For Hugo
hugo && python postprocess.py

# For Jekyll
jekyll build && python postprocess.py

⚙️ Configuration Options

Both modes support the same configuration options:

Option	Type	Default	Description
`verbose`	bool	`True`	Enable detailed console output
`enabled`	bool	`True`	Enable/disable processing
`default_image`	str	`None`	Fallback image URL for meta tags
`default_author`	str	`None`	Default GitHub author email
`add_desc`	bool	`True`	Generate meta description tags
`add_image`	bool	`True`	Generate meta image tags
`add_keywords`	bool	`True`	Generate meta keyword tags
`add_share_buttons`	bool	`True`	Add social share buttons
`add_authors`	bool	`False`	Display Git author info
`add_json_ld`	bool	`False`	Add JSON-LD structured data
`add_css`	bool	`True`	Include inline CSS styles
`add_copy_llm`	bool	`True`	Add "Copy for LLM" button
`add_llms_txt`	bool	`True`	Generate an `llms.txt` index

🧩 How It Works

The tool processes HTML pages to enhance them with metadata and interactive elements:

Meta Description Generation

Extracts the first paragraph from your content and generates <meta name="description"> tags for SEO.

Meta Image Tagging

Identifies the first image in the content or uses the default image for og:image and twitter:image tags.

Appends pre-styled Twitter and LinkedIn sharing buttons to your content.

Git Information Display

Retrieves Git history to show creation/update dates and author avatars at the bottom of pages.

JSON-LD Structured Data

Generates Article and FAQPage schema for better search engine understanding.

Copy for LLM Button

Adds a button next to the "Edit this page" button that fetches the raw Markdown and copies it to clipboard, perfect for sharing with AI assistants.

💡 Architecture

The codebase is organized for maximum code reuse:

plugin/
├── __init__.py       # Package metadata
├── processor.py      # ⭐ Core HTML processing logic
├── main.py          # MkDocs plugin wrapper
├── postprocess.py   # Standalone postprocess wrapper
└── utils.py         # Helper functions

Both plugin mode and postprocess mode use the same process_html() function in processor.py, ensuring identical output regardless of which mode you use.

📊 Plugin Mode vs Postprocess Mode

Feature	Plugin Mode	Postprocess Mode
Works with	MkDocs only	Any static site generator
Processing time	During build (per-page)	After build (batch)
Configuration	`mkdocs.yml`	Python script
Hot reload	✅ Yes	❌ No (rebuild required)
Git info	✅ Yes	✅ Yes
Best for	MkDocs projects	Zensical, Hugo, Jekyll, etc.

🤝 Contribute

Collaboration fuels innovation! 🤗 The success of Ultralytics' open-source projects 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.

Please see our Contributing Guide for details. Filling out our Survey also provides valuable feedback. We sincerely appreciate 🙇‍♂️ every contribution!

📜 License

Ultralytics provides two licensing options:

AGPL-3.0 License: Ideal for students, researchers, and enthusiasts, this OSI-approved license promotes open collaboration and knowledge sharing. See the LICENSE file for details.
Enterprise License: Designed for commercial applications, this license allows seamless integration of Ultralytics software into commercial products, bypassing AGPL-3.0 requirements. Visit Ultralytics Licensing for details.

✉️ Connect with Us

Encountered a bug or have an idea? Visit GitHub Issues to report problems or suggest enhancements. For discussions and community support, join our Discord server and check out Ultralytics Reddit.

Metadata

Release files for mkdocs-ultralytics-plugin 0.2.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-ultralytics-plugin 0.2.5
File	Size	Uploaded
mkdocs_ultralytics_plugin-0.2.5.tar.gz	32.1 kB	Jun 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-ultralytics-plugin 0.2.5
File	Interpreter	ABI	Platform	Reset
mkdocs_ultralytics_plugin-0.2.5-py3-none-any.whl 33.6 kB Jun 30, 2026	Python 3	none	any	Details

Total release size: 65.6 kB

Release files / mkdocs_ultralytics_plugin-0.2.5.tar.gz

Download URL	mkdocs_ultralytics_plugin-0.2.5.tar.gz
Size	32.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`dde892fed2adeed6e591cddb056bde3df259e85f109779a5a15a8d60bc11e1a1`
BLAKE2b-256 checksum How to use checksums	`4efbf3579ac934c2526689ca329ecbfe2ae6eebc418332af407f9610b342496d`
Upload date	Jun 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ultralytics/mkdocs
Publishing commit: github.com/ultralytics/mkdocs/tree/ad77effd9621156c0da9300b348498396cc0148f

Workflow

Publishing configuration: github.com/ultralytics/mkdocs/blob/ad77effd9621156c0da9300b348498396cc0148f/.github/workflows/publish.yml
Publishing logs: github.com/ultralytics/mkdocs/actions/runs/28432991312/attempts/1

Artifact

Subject: mkdocs_ultralytics_plugin-0.2.5.tar.gz
SHA-256 checksum: dde892fed2adeed6e591cddb056bde3df259e85f109779a5a15a8d60bc11e1a1 Verifying attestations

Release files / mkdocs_ultralytics_plugin-0.2.5-py3-none-any.whl

Download URL	mkdocs_ultralytics_plugin-0.2.5-py3-none-any.whl
Size	33.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`fe5b55200635d4817b0a027aa249595dfa7b2071f97eab6054aff01722264fd2`
BLAKE2b-256 checksum How to use checksums	`c26b169e5d7a8d2ed56e911256eb38e06ce334624b2bf5ea09cb0f67a51b54a8`
Upload date	Jun 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ultralytics/mkdocs
Publishing commit: github.com/ultralytics/mkdocs/tree/ad77effd9621156c0da9300b348498396cc0148f

Workflow

Publishing configuration: github.com/ultralytics/mkdocs/blob/ad77effd9621156c0da9300b348498396cc0148f/.github/workflows/publish.yml
Publishing logs: github.com/ultralytics/mkdocs/actions/runs/28432991312/attempts/1

Artifact

Subject: mkdocs_ultralytics_plugin-0.2.5-py3-none-any.whl
SHA-256 checksum: fe5b55200635d4817b0a027aa249595dfa7b2071f97eab6054aff01722264fd2 Verifying attestations