Can You Set Meta Descriptions in MkDocs? 3 Implementation Methods with Examples¶

Conclusion: Yes, MkDocs Supports Meta Descriptions¶

MkDocs natively supports meta description configuration with multiple implementation approaches. From global defaults to page-specific optimization, MkDocs provides flexible solutions for SEO requirements. This article covers three primary methods with practical examples.

Method 1: Global Configuration (Site-wide Default)¶

The simplest approach is defining a default meta description in mkdocs.yml for the entire site.

# mkdocs.yml
site_name: Your Site
site_description: Default meta description for the entire site (50-160 chars recommended)

This serves as a fallback when individual pages don't specify their own descriptions.

Method 2: Page-Level Meta Description Settings¶

Use YAML front matter at the beginning of each Markdown file to set page-specific meta descriptions.

---
description: Page-specific meta description that appears in search results.
---

# Page Title

Content starts here...

Priority Order: 1. Page-level description (highest priority) 2. Site-wide site_description (fallback)

Method 3: Plugin-Based Automation¶

Material for MkDocs Built-in Meta Plugin¶

Material for MkDocs theme includes a meta plugin that enables directory-level metadata management.

# mkdocs.yml
plugins:
  - meta

Place a .meta.yml file in any directory to apply metadata to all files within that directory.

# docs/guide/.meta.yml
description: Standard meta description for guide section

mkdocs-meta-descriptions-plugin¶

This plugin automatically generates meta descriptions from the first paragraph of each page.

plugins:
  - meta-descriptions:
      enable_checks: true
      min_length: 50      # Minimum character count
      max_length: 160     # Maximum (SEO recommended)
      trim: true          # Auto-trim if exceeded

Implementation Example and Verification¶

Sample HTML Output

<head>
  <meta name="description" content="Learn how to configure meta descriptions in MkDocs for SEO optimization.">
  <!-- Other meta tags -->
</head>

Verification Commands¶

# Build and check HTML output
mkdocs build --strict
grep -r "meta name=\"description\"" site/

SEO Best Practices¶

Character Limits: Keep within 50-160 characters (2025 Google recommendations)
User Intent Focus: Prioritize natural descriptions over keyword stuffing
Page-by-Page Optimization: Customize important pages individually
Regular Reviews: Adjust based on search performance

Summary¶

MkDocs offers flexible meta description configuration through standard features and plugins. Choose the appropriate method based on your site's scale and SEO requirements. While global settings suffice for small sites, page-level optimization is recommended for SEO-focused projects.