# MkDocs Advanced SEO Plugin

[![PyPI version](https://badge.fury.io/py/mkdocs-advanced-seo.svg)](https://badge.fury.io/py/mkdocs-advanced-seo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install mkdocs-advanced-seo
```

## Usage

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

```yaml
plugins:
  - advanced-seo
```

### Configuration

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

```yaml
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:

```yaml
---
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:

   ```bash
   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.
