MkDocs Advanced SEO Plugin

A comprehensive, deep, and powerful SEO plugin for MkDocs. This plugin is designed to squeeze every bit of SEO performance out of your MkDocs site by automatically generating advanced meta tags, Open Graph tags, Twitter Cards, and structured data (JSON-LD), while handling edge cases and missing data gracefully.

Features

• Deep SEO Optimization: Automatically inserts a full suite of meta tags (description, keywords, author, robots, etc.).
• Open Graph Support: Fully treats your pages as rich objects for social networks (Facebook, LinkedIn, etc.) with og:title, og:description, og:image, og:url, og:site_name, and og:locale.
• Twitter Cards Integration: Optimizes tweets with summary cards, images, and creator/site attributions.
• JSON-LD Structured Data: Automatically generates Google-compliant WebPage and BreadcrumbList schema.org Data.
• Smart Date Handling: Seamlessly integrates with mkdocs-document-dates (and similar plugins) to correctly utilize creation and update timestamps (supports complex ISO formats like 2025-07-23T07:55:08.813591+08:00).
• Canonical URLs: Prevents duplicate content penalties by automatically generating correct canonical links.
• Robust Fallbacks: Designed to work even when metadata is missing, ensuring your site always builds without errors.

Installation

pip install mkdocs-advanced-seo

Usage

Add advanced-seo to your mkdocs.yml plugins list:

plugins:
  - advanced-seo

Configuration

The plugin is "batteries included" and works out of the box, but you can deeply customize it:

plugins:
  - advanced-seo:
      url_base: "https://yourwebsite.com" # Highly Recommended for canonical/OG links
      
      # Feature Toggles
      use_canonical_url: true
      use_open_graph: true
      use_twitter_cards: true
      add_schema_org_json_ld: true
      
      # Default Values (Fallbacks)
      og_type: "website"
      og_image: "assets/default-share-image.jpg"
      og_locale: "en_US"
      
      # Twitter Defaults
      twitter_card_type: "summary_large_image"
      twitter_site: "@yourproject"
      twitter_creator: "@yourhandle"
      
      # Advanced Integration
      support_document_dates: true # Auto-detect dates from other plugins

Frontmatter Overrides

You can control SEO parameters on a per-page basis using standard YAML frontmatter:

---
title: My Awesome Page
description: A custom description for search engines.
image: assets/page-specific-image.jpg
date: 2023-05-20
---

Development and Testing

This project includes a test suite to verify SEO tag generation.

1. Clone the repository.

2. Install dependencies: pip install -e .

3. Run verification:

   python verify.py
   

Support & Contributing

This project is personally maintained by the author.

• Bug Reports: Welcome! Please open an issue if you find a bug or incorrect SEO tag generation.
• Contributions: Pull requests for bug fixes and corrections are appreciated. Major feature requests may not be prioritized due to time constraints.

[!NOTE] This project structure and code were generated by Antigravity (Google DeepMind) under human supervision. Verification and acceptance were performed by the user.