SEO

The theme handles SEO automatically using page metadata and site-level configuration.

Site-level configuration

site_name: My Project
site_url: https://example.com          # Required for canonical URLs and sitemap
site_description: Short description    # Used as default meta description
site_author: Your Name

extra:
  seo:
    og_image: assets/img/og-default.png   # Default Open Graph image
    twitter_site: "@yourhandle"
    twitter_creator: "@yourhandle"

Always set site_url

Without site_url, canonical URLs, the sitemap link, and absolute Open Graph image URLs will not work correctly.

Per-page overrides via frontmatter

Add a YAML frontmatter block to any Markdown file to override the defaults:

---
title: Custom Page Title
description: A specific description for this page, used in search results.
image: assets/img/custom-page-og.png
noindex: true
---

# Page content here
Field Description
title Overrides the <title> tag and all OG/Twitter title fields
description Overrides the meta description for this page
image Overrides the Open Graph image for this page
noindex Set to true to add <meta name="robots" content="noindex, nofollow">

What gets generated automatically

For every page, partials/seo.html generates:

  • <meta name="description"> and <meta name="author">
  • <meta name="robots"> (index, follow unless noindex: true)
  • <link rel="canonical"> — uses page.canonical_url from MkDocs
  • <link rel="sitemap"> — points to /sitemap.xml (auto-generated by MkDocs)
  • Open Graph tags: og:type, og:title, og:description, og:url, og:image
  • Twitter Card tags: twitter:card, twitter:title, twitter:description, twitter:image
  • <meta name="theme-color"> for mobile browser chrome
  • JSON-LD structured data (WebSite for the home page, TechArticle for inner pages)

Sitemap

MkDocs generates sitemap.xml automatically on every mkdocs build. No plugin configuration is needed — just make sure site_url is set.

Open Graph image

The image path is resolved relative to docs/. For a path like assets/img/og.png, place the file at docs/assets/img/og.png.

Recommended size: 1200 × 630 pixels.