Markdown Extensions

MkDocs supports Python-Markdown extensions that enhance the standard Markdown syntax with additional features and capabilities.

Overview

Markdown extensions provide:

• Enhanced syntax - Additional markup options
• Better formatting - Tables, footnotes, and more
• Meta information - Document metadata
• Smart processing - Automatic conversions
• HTML integration - Mix Markdown with HTML
• Custom elements - Extend with your own syntax

Core Extensions

Table of Contents

Generate automatic table of contents:

markdown_extensions:
  - toc:
      permalink: true
      title: On this page
      toc_depth: 3

Features: - permalink - Add anchor links to headings - title - TOC section title - toc_depth - Maximum heading level - slugify - Custom slug function

Tables

Enhanced table support:

markdown_extensions:
  - tables

Example:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Abbreviations

Define abbreviations with tooltips:

markdown_extensions:
  - abbr

Usage:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Result: The HTML specification is maintained by the W3C.

Admonition

Create callout boxes:

markdown_extensions:
  - admonition

See the Admonitions page for detailed usage.

Attribute Lists

Add HTML attributes to elements:

markdown_extensions:
  - attr_list

Examples:

# Heading with ID {#custom-id}

[Link with class](https://example.com){.external-link}

<img loading="lazy" src="image.jpg" alt="Image with attributes">{width="300" height="200"}

Paragraph with custom class.
{.custom-paragraph}

Definition Lists

Create term definitions:

markdown_extensions:
  - def_list

Example:

Apple
:   A fruit that grows on trees

Python
:   A programming language
:   A type of snake

Footnotes

Add footnotes to your content:

markdown_extensions:
  - footnotes

Example:

This is a statement[^1] that needs a citation[^2].

[^1]: This is the first footnote.
[^2]: This is the second footnote.

Meta-Data

Add YAML front matter:

markdown_extensions:
  - meta

Example:

---
title: Page Title
author: John Doe
date: 2024-01-15
tags: [python, tutorial]
---

# Document content starts here

Markdown in HTML

Enable Markdown inside HTML:

markdown_extensions:
  - md_in_html

Example:

<div markdown>
# This is a heading

And this is a **paragraph** with *emphasis*.
</div>

Python-Markdown Extensions

Extra

Bundle of useful extensions:

markdown_extensions:
  - extra

Includes: - abbr - attr_list - def_list - footnotes - md_in_html - tables

CodeHilite (Deprecated)

For syntax highlighting (use Pygments instead):

markdown_extensions:
  - codehilite:
      guess_lang: false
      use_pygments: true

Fenced Code Blocks

Enable GitHub-style code blocks:

markdown_extensions:
  - fenced_code

Smart Strong

Improve bold/emphasis handling:

markdown_extensions:
  - smart_strong

SmartyPants

Convert quotes and dashes:

markdown_extensions:
  - smarty:
      smart_quotes: true
      smart_dashes: true
      smart_ellipses: true

Configuration

Basic Setup

# mkdocs.yml
markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - meta
  - md_in_html
  - toc:
      permalink: true
  - tables

  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.details
  - pymdownx.emoji
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true

Advanced Configuration

markdown_extensions:
  # TOC with custom slugify
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
      toc_depth: 3

  # Highlight with line numbers
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true

  # SuperFences with custom handlers
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
        - name: math
          class: arithmatex
          format: !!python/object/apply:pymdownx.arithmatex.arithmatex_fence_format

  # Emoji with custom icons
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

Extension Categories

Text Processing

Extension	Purpose	Example
betterem	Better emphasis	**_bold italic_**
caret	Superscript	x^2^
mark	Highlight	==marked==
tilde	Subscript/strike	H~2~O, ~~deleted~~
smartsymbols	Smart symbols	(c) → ©
keys	Keyboard keys	++ctrl+c++

Content Organization

Extension	Purpose	Features
tabbed	Content tabs	Organize alternatives
details	Collapsible	Hide/show content
snippets	Include files	Reuse content
blocks	Block elements	Custom containers

Code Features

Extension	Purpose	Configuration
highlight	Syntax highlighting	Line numbers, highlighting
inlinehilite	Inline code	Language-specific
superfences	Nested blocks	Custom processors
striphtml	Remove HTML	Security feature

Custom Extensions

Creating Extensions

Basic extension structure:

# my_extension.py
from markdown import Extension
from markdown.preprocessors import Preprocessor

class MyPreprocessor(Preprocessor):
    def run(self, lines):
        new_lines = []
        for line in lines:
            # Process line
            new_lines.append(line)
        return new_lines

class MyExtension(Extension):
    def extendMarkdown(self, md):
        md.preprocessors.register(
            MyPreprocessor(md),
            'my_preprocessor',
            priority=25
        )

def makeExtension(**kwargs):
    return MyExtension(**kwargs)

Using Custom Extensions

markdown_extensions:
  - my_extension:
      option1: value1
      option2: value2

Best Practices

1. Start Simple

Begin with essential extensions:

markdown_extensions:
  - admonition
  - codehilite
  - toc:
      permalink: true

2. Progressive Enhancement

Add extensions as needed:

# Phase 1: Basics
- toc
- admonition
- codehilite

# Phase 2: Enhanced
- attr_list
- def_list
- footnotes

# Phase 3: Advanced
- pymdownx.superfences
- pymdownx.tabbed
- pymdownx.arithmatex

3. Test Compatibility

Some extensions may conflict: - Test new extensions thoroughly - Check rendering in different contexts - Verify mobile compatibility

4. Document Usage

Create a style guide:

# Markdown Style Guide

## Admonitions
Use `!!! note` for general information
Use `!!! warning` for important cautions

## Code Blocks
Always specify language: ` ```python`
Use line highlighting: ` ```python hl_lines="2-4"`

## Tables
Keep tables simple and readable
Use alignment sparingly

Performance Considerations

Heavy Extensions

Some extensions impact build time: - search - Indexes all content - minify - Processes all HTML - Complex regex patterns

Optimization

# Disable unused features
markdown_extensions:
  - pymdownx.highlight:
      guess_lang: false  # Faster

  - toc:
      toc_depth: 3  # Limit depth

Troubleshooting

Common Issues

1. Extension not found

   pip install pymdown-extensions
   

2. Conflict between extensions

3. Check extension order

4. Some extensions must load first

5. Rendering issues

6. Verify syntax is correct
7. Check extension configuration
8. Test with minimal config

Debug Mode

# Enable debug output
import logging
logging.basicConfig(level=logging.DEBUG)

Migration Guide

From GitHub Markdown

GitHub	MkDocs Extension
Tables	tables
Task lists	pymdownx.tasklist
Strikethrough	pymdownx.tilde
Emoji	pymdownx.emoji
Syntax highlight	pymdownx.highlight

From CommonMark

Add extensions for CommonMark features:

markdown_extensions:
  - tables
  - fenced_code
  - footnotes
  - attr_list

Resources

Documentation

• Python-Markdown Extensions
• PyMdown Extensions
• Writing Extensions

Extension Lists

• Awesome MkDocs
• MkDocs Plugins

See Also

• PyMdown Extensions - Enhanced extensions
• Code Blocks - Code highlighting features
• Content Tabs - Tabbed content
• Admonitions - Callout boxes