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.