MkDocs SEO audit

What the audit checks on MkDocs sites

mkdocs.yml configuration and Material theme meta tag output

MkDocs SEO configuration is primarily driven by mkdocs.yml. The audit validates what is rendered in the generated static HTML: whether site_name appears in <title> tags (Material for MkDocs formats page titles as "Page Title - Site Name"); whether meta description is populated from the page's frontmatter description field or from the first paragraph of page content (Material for MkDocs uses the first paragraph as fallback if no description is set in frontmatter); whether OG title (og:title), OG description (og:description), and OG image (og:image) are present with absolute URLs (OG image requires a social.cards plugin or explicit image configuration in theme.social under extra); whether canonical tags are correctly generated using site_url from mkdocs.yml (absent if site_url is not configured); and whether the page title frontmatter field (overriding the H1 as the page title in meta tags) is correctly applied. The audit also checks for noindex on special pages like the search UI.

URL structure and use_directory_urls configuration

MkDocs URL structure is controlled by the use_directory_urls setting in mkdocs.yml. When true (the default), MkDocs generates clean URLs: docs/getting-started.md becomes /getting-started/ (an index.html in a directory). When false, it generates /getting-started.html. For SEO: directory URLs are preferable for cleaner, extension-free URLs. The URL is derived from the file path in docs/ — the filename becomes the URL slug. File naming matters: prefer-hyphenated-slugs.md produces better URLs than pageAbout.md or page_about.md. The audit checks: whether use_directory_urls matches the expected URL format; whether the navigation structure in mkdocs.yml creates a logical hierarchy that maps to URL depth; whether nav aliases are configured correctly for renamed or moved pages (broken links in nav produce 404s after deployment); and whether versioned documentation subdirectories are excluded from the primary sitemap or marked noindex.

JSON-LD structured data via theme overrides

MkDocs generates no JSON-LD by default — structured data requires theme customisation. The audit validates: whether Article JSON-LD is present in the page's static HTML output (present only if a theme override has been implemented); whether the Article schema includes required properties (headline from page title, datePublished from page meta.date frontmatter if present, author Person from site author config or page frontmatter, image — the most commonly missing property on documentation sites); whether BreadcrumbList JSON-LD reflects the docs navigation hierarchy; whether FAQPage JSON-LD is present on pages structured as Q&A content; and whether all JSON-LD is in the server-rendered static HTML (not client-side injected via JavaScript, which requires Googlebot rendering). Documentation sites without JSON-LD miss HowTo and Article rich result eligibility. Material for MkDocs theme overrides allow Jinja2 template access to page.meta (frontmatter fields), config.site_url, page.url, and page.title to build structured data server-side.

MkDocs sitemap generation and robots.txt

MkDocs generates sitemap.xml by default when site_url is set in mkdocs.yml — the sitemap plugin is enabled by default in Material for MkDocs. The audit validates: whether sitemap.xml is accessible at the root URL; whether all documentation pages are included (pages excluded from nav and pages with search.exclude frontmatter are typically excluded); whether sitemap entries use absolute URLs (requires site_url in mkdocs.yml); whether the sitemap uses <lastmod> dates (available if documentation pages have date or git_revision_date_localized metadata); whether the MkDocs search page (/search/) is excluded from the sitemap; whether version-specific subdirectory pages (/v1.2/, /v1.3/) are excluded if only the latest version should be indexed; whether robots.txt exists in the site root (requires manual placement of robots.txt in docs/ — MkDocs copies it to site/); and whether robots.txt declares the sitemap URL.

Core Web Vitals for MkDocs documentation sites

MkDocs generates fully static HTML files from Markdown — TTFB is excellent when hosted on a CDN or GitHub Pages, typically 20–80ms from edge locations. The main Core Web Vitals risks on MkDocs sites are theme-dependent: (1) LCP — documentation pages typically have no large hero images; the LCP element is usually a heading or first paragraph of text. Text LCP renders quickly on static pages. If the theme loads a large logo image above the fold, add fetchpriority="high" to it in the theme override. (2) CLS — Material for MkDocs loads fonts from Google Fonts CDN by default (Roboto). Google Fonts CSS includes font-display: swap, which reduces CLS risk, but FOUT (Flash of Unstyled Text) is common. Set font: false under theme.features in mkdocs.yml (Material) to use system fonts and eliminate font CLS entirely. (3) INP — most documentation sites have minimal JavaScript; the main INP risk is from the instant search feature (Material's search plugin loads a large search index on interaction). Tab switching and navigation in the sidebar are typically fast. Measure with real CrUX field data — documentation sites often have developer audiences on fast connections, but mobile users on slower connections may have different experiences.

AI visibility and GEO score for MkDocs documentation sites

MkDocs documentation sites are excellent candidates for AI citation: technical documentation answers specific questions clearly, and the static HTML output is immediately accessible to AI crawlers without JavaScript rendering. The five AI visibility signals for MkDocs: (1) AI crawler access in robots.txt — add explicit User-agent allowances for GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and CCBot in docs/robots.txt (MkDocs copies it to site/). Without robots.txt, crawlers are allowed by default, but explicit configuration is better practice. (2) llms.txt — create docs/llms.txt following the llms.txt spec; MkDocs copies it to site/llms.txt at build. Documentation sites are particularly valuable candidates for llms.txt because they contain authoritative technical reference content AI systems should cite correctly. (3) FAQPage JSON-LD — requires theme override (Jinja2 template) for server-rendered structured data on FAQ pages. (4) Question-heading ratio — technical documentation naturally uses question-format headings ("How do I configure X?", "What does Y do?"); ensure ≥20% of H2/H3 headings are phrased as questions for GEO score. (5) Content chunkability — MkDocs Markdown content with section headings creates well-chunked passages; verify that each section under an H2/H3 is ≤400 words for clean AI extraction.

How to audit your MkDocs documentation site

1. Enter any URL from your MkDocs site — the documentation root, a specific page, or a versioned docs subdirectory.
2. DeepSEOAnalysis validates the static HTML output: Material theme-generated canonical tags and meta tags, JSON-LD structured data completeness, robots.txt AI crawler access, sitemap presence, and Core Web Vitals from real CrUX field data.
3. Review findings: missing site_url configuration (canonical tag absence), structured data gaps, AI visibility score, and Core Web Vitals issues from real user sessions.
4. Share the audit URL with your documentation team — no login required to view results.

MkDocs SEO frequently asked questions

Does MkDocs generate canonical tags automatically?

It depends on the theme. Material for MkDocs (the dominant MkDocs theme) generates canonical tags automatically when site_url is configured in mkdocs.yml. The canonical tag uses the site_url combined with the page path to produce an absolute canonical URL. Without site_url configured, Material for MkDocs omits the canonical tag. The built-in MkDocs default theme (mkdocs theme) does not generate canonical tags — they must be added via theme override. To verify canonical output: run mkdocs build, open the site/ output directory, open any generated HTML file, and search for <link rel="canonical"> in the <head>. If it\'s absent, either site_url is not set in mkdocs.yml (add it: site_url: https://docs.example.com/) or the theme doesn\'t support auto-canonical generation (override the theme base.html template to add it manually).

How do you add JSON-LD structured data to MkDocs?

MkDocs does not generate JSON-LD by default — it must be added via theme customization. For Material for MkDocs: (1) **Theme override** — create a docs/overrides/main.html template that extends the base Material template and injects a <script type="application/ld+json"> block in the {% block extrahead %} section. Use Jinja2 template variables: page.title (the page title), page.meta.date (from frontmatter), config.site_url + page.url (for the canonical @id), config.site_url + config.theme.favicon (for the logo image). (2) **extra_javascript** — add a JavaScript file that runs after page load to inject JSON-LD into the DOM. This is client-side only — Googlebot would need to render the page to see it. The theme override approach is preferable because the JSON-LD is in the server-rendered static HTML. For most MkDocs documentation sites, the most useful schema types are Article (for technical documentation pages), BreadcrumbList (for the navigation breadcrumb), Organization/WebSite (in the base template), and FAQPage (for pages structured as Q&A).

How do you add a robots.txt to a MkDocs site?

MkDocs does not generate robots.txt automatically. To include a robots.txt in the built site output: place a robots.txt file in the docs/ directory (your documentation source directory). MkDocs copies all non-Markdown files from docs/ to site/ at build time. A robots.txt at docs/robots.txt will appear at site/robots.txt, which serves from the root of your documentation site. Example robots.txt for MkDocs documentation: Sitemap: https://docs.example.com/sitemap.xml with User-agent: * followed by Allow: / followed by explicit User-agent entries for GPTBot and ClaudeBot. The MkDocs built-in sitemap (enabled by default with Material for MkDocs when site_url is set) generates sitemap.xml in site/ — declare it in robots.txt as shown above. For versioned documentation (using mike or similar), each version has its own subdirectory — the robots.txt in the root should allow all; individual version directories may use noindex if only the latest version should be indexed.

What are the most common SEO problems on MkDocs documentation sites?

The most common MkDocs SEO issues: (1) **Missing site_url in mkdocs.yml** — without site_url, Material for MkDocs cannot generate canonical tags (the absolute URL isn\'t known at build time). This is the single highest-impact configuration for SEO on MkDocs sites. (2) **Versioned documentation indexed incorrectly** — when using mike for versioned docs, older version directories (/v1.2/, /v1.3/, etc.) often get indexed. These should have a noindex robots meta tag or be blocked in robots.txt; only the latest stable version should be indexed. (3) **No robots.txt** — MkDocs doesn\'t generate robots.txt, and many deployments never add one — no sitemap declaration for crawlers. (4) **No JSON-LD structured data** — MkDocs generates no structured data by default. Article and BreadcrumbList JSON-LD require theme overrides. (5) **Search index page indexed** — MkDocs/Material generates a search/ page (/search/index.html) with a search UI. This page should be noindexed (Material for MkDocs noindexes it by default with the search plugin configured). (6) **Tag pages thin content** — if using the Material for MkDocs tags plugin, tag index pages may be thin and should be evaluated for noindex or content enrichment.