Skip to content

XML Sitemap

XML sitemaps help search engines discover and index your documentation by providing a roadmap of all available pages. MkDocs automatically generates sitemaps when properly configured.

Overview

The MkDocs4 Ultimate Guide includes automatic sitemap generation that:

  • Creates a complete sitemap.xml file for all documentation pages
  • Updates automatically with new content
  • Integrates with search engines and SEO tools
  • Supports modern navigation features like instant navigation
  • Includes proper last modification dates

Features

Automatic Generation

Sitemaps are generated automatically during the build process without requiring additional plugins: - Built-in functionality: Part of MkDocs core - Complete coverage: Includes all pages in navigation - SEO optimized: Proper XML structure and metadata

Search Engine Integration

The sitemap helps search engines: - Discover all documentation pages - Understand site structure and hierarchy - Prioritize indexing of important content - Track content updates and changes

Modern Web Standards

Generated sitemaps follow: - XML Sitemap Protocol 0.9 - Search engine best practices - W3C XML standards

Configuration

Site URL Requirement

Sitemap generation requires the site_url setting in mkdocs.yml:

# Essential for sitemap generation
site_url: https://mkdocs-ultimate.example.com

# This setting is required for:
# - Sitemap XML generation
# - Instant navigation feature
# - Social media cards
# - RSS feeds

Required Setting

Without site_url, the sitemap will be empty. This setting is essential for proper sitemap generation.

The sitemap includes all pages referenced in the navigation:

nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - Features:
    - features/index.md
    - RSS Feeds: features/rss-feeds.md
    - Sitemap: features/sitemap.md
  # All these pages will appear in sitemap.xml

Instant Navigation Integration

When using Material's instant navigation, the sitemap is essential:

theme:
  features:
    - navigation.instant     # Requires sitemap.xml
    - navigation.tracking    # URL updates with anchors

Sitemap Structure

XML Format

Generated sitemaps follow the standard XML structure:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>https://mkdocs-ultimate.example.com/</loc>
        <lastmod>2025-05-24</lastmod>
    </url>
    <url>
        <loc>https://mkdocs-ultimate.example.com/getting-started/</loc>
        <lastmod>2025-05-24</lastmod>
    </url>
    <url>
        <loc>https://mkdocs-ultimate.example.com/features/rss-feeds/</loc>
        <lastmod>2025-05-24</lastmod>
    </url>
    <!-- Additional URLs... -->
</urlset>

URL Elements

Each URL entry includes:

  • <loc>: Absolute URL to the page
  • <lastmod>: Last modification date (ISO format)
  • <changefreq>: Not used by MkDocs (optional in protocol)
  • <priority>: Not used by MkDocs (deprecated by search engines)

Usage and Implementation

Automatic Generation

Sitemaps are generated during every build:

# Build documentation (includes sitemap generation)
mkdocs build

# Verify sitemap was created
ls site/sitemap.xml

# View sitemap content
cat site/sitemap.xml

Search Console Integration

Submit sitemaps to search engines:

Google Search Console

  1. Go to Google Search Console
  2. Select your property
  3. Navigate to Sitemaps in the sidebar
  4. Submit: https://your-site.com/sitemap.xml

Bing Webmaster Tools

  1. Go to Bing Webmaster Tools
  2. Select your site
  3. Navigate to Sitemaps
  4. Submit sitemap URL

Robots.txt Integration

Include sitemap reference in robots.txt:

User-agent: *
Allow: /

# Sitemap location
Sitemap: https://your-site.com/sitemap.xml

Validation and Testing

XML Validation

Validate the generated sitemap:

# Check XML syntax
xmllint --noout site/sitemap.xml

# Format and display sitemap
xmllint --format site/sitemap.xml

Sitemap Validation Tools

Use online validation tools:

Testing Commands

# Count URLs in sitemap
grep -c "<url>" site/sitemap.xml

# Extract all URLs
grep -o 'https://[^<]*' site/sitemap.xml

# Check last modification dates
grep "<lastmod>" site/sitemap.xml

HTTP Testing

When deployed, test HTTP accessibility:

# Check sitemap accessibility
curl -I https://your-site.com/sitemap.xml

# Expected response
HTTP/1.1 200 OK
Content-Type: application/xml

SEO Benefits

Search Engine Discovery

Sitemaps help search engines:

  1. Complete indexing: Discover all pages
  2. Efficient crawling: Understand site structure
  3. Update tracking: Monitor content changes
  4. Priority guidance: Focus on important content

Analytics Integration

Monitor sitemap performance:

  • Google Search Console: Sitemap coverage reports
  • Bing Webmaster Tools: Indexing statistics
  • Third-party SEO tools: Sitemap analysis

Best Practices

  1. Regular updates: Automatic generation ensures freshness
  2. Clean URLs: Use consistent URL structure
  3. Mobile optimization: Ensure mobile-friendly pages
  4. Page quality: Include only valuable content

Troubleshooting

Common Issues

Empty Sitemap

  • Cause: Missing site_url configuration
  • Solution: Add site_url to mkdocs.yml

Missing Pages

  • Cause: Pages not included in navigation
  • Solution: Add pages to nav configuration

Invalid URLs

  • Cause: Incorrect site_url format
  • Solution: Use absolute URL with protocol

Build Errors

  • Cause: Configuration conflicts
  • Solution: Check MkDocs build logs

Debug Commands

# Verbose build to see sitemap generation
mkdocs build --verbose

# Check configuration
mkdocs config

# Validate navigation structure
python -c "
import yaml
with open('mkdocs.yml') as f:
    config = yaml.safe_load(f)
    print('Site URL:', config.get('site_url'))
    print('Navigation pages:', len(config.get('nav', [])))
"

Advanced Configuration

Custom Templates

While MkDocs doesn't support custom sitemap templates directly, you can:

  1. Post-process sitemaps: Use build hooks to modify generated XML
  2. Additional sitemaps: Create specialized sitemaps for different content
  3. Integration scripts: Combine with external tools

Multi-language Sites

For international sites:

# Configure language and locale
theme:
  language: en

# Use hreflang in custom templates
extra:
  alternate:
    - name: English
      link: /en/
      lang: en
    - name: Français
      link: /fr/
      lang: fr

Performance Optimization

  1. Compression: Enable gzip compression for XML files
  2. Caching: Configure appropriate cache headers
  3. CDN integration: Distribute sitemaps globally
  4. Size management: Monitor sitemap size (max 50MB/50,000 URLs)

External Resources