Skip to content

How to Fix MkDocs Meta Tags

DodaTech Updated 2026-06-24 2 min read

In this tutorial, you'll learn about How to Fix MkDocs Meta Tags. We cover key concepts, practical examples, and best practices.

Your MkDocs pages are missing meta descriptions, Open Graph tags, or custom <head> content. MkDocs does not auto-generate meta tags beyond the page title.

The Wrong Way

# Page Title
<meta name="description" content="This is my page">

HTML tags written in markdown are not processed into the page `<head>`. They appear as visible text in the body.

## The Right Way

### Step 1: Add page-specific meta tags in frontmatter

```yaml
---
title: Getting Started
description: Learn how to install and configure the tool in under 5 minutes.
---

MkDocs Material theme reads description from frontmatter and adds it as a <meta> tag.

Step 2: Add Open Graph tags in mkdocs.yml

# mkdocs.yml
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-org

  open_graph:
    title: "My Documentation"
    description: "Learn how to use our tools effectively"
    image: assets/images/og-image.png

Step 3: Use custom head HTML injection

# mkdocs.yml
extra:
  head:
    - '<meta name="robots" content="index,follow">'
    - '<link rel="canonical" href="https://example.com/docs/">'

Step 4: Install meta-tags plugin (for non-Material themes)

pip install mkdocs-meta-tags-plugin

# mkdocs.yml
plugins:
  - meta-tags

This plugin converts YAML frontmatter fields into HTML meta tags automatically.

Page <head> includes: description, OG title, OG image, canonical URL — verified with browser <a href="/web-development/tools/chrome-devtools/">DevTools</a>.

Prevention

  • Add a description field to every page's frontmatter as a habit.
  • Test meta tags with social share preview tools (LinkedIn Inspector, Twitter Card Validator).
  • The metadata injection pattern is used by Doda Browser's bookmark exporter — each bookmark gets proper HTML meta tags for share previews.

Common Mistakes with meta tags

  1. Misunderstanding that String is [Char] with poor performance for large text operations
  2. Using foldl instead of foldl' causing stack overflow on large lists
  3. Forgetting deriving (Show, Eq) on custom data types needed for debugging

These mistakes appear frequently in real-world MKDOCS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

### Why are my MkDocs meta tags not appearing on social media?

Social media crawlers require Open Graph (og:) tags specifically. The description frontmatter alone does not create OG tags. Use the open_graph extra config or the mkdocs-meta-tags-plugin to generate proper OG tags.

Can I add different meta tags per page?

With MkDocs Material, add description in frontmatter for per-page descriptions. For other meta tags, use the mkdocs-meta-tags-plugin which reads any YAML frontmatter field and generates corresponding HTML meta tags.

How do I prevent a page from being indexed?

Add to the page's frontmatter:

---
robots: noindex, nofollow
---

Then use a custom head injection that reads this value and generates <meta name="robots">. This requires a custom hook or plugin.

← Previous How to Fix MkDocs Material Build Errors Next → How to Fix MkDocs Navigation Configuration

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Quick Fix