Footnotes

Footnotes allow you to add references, citations, and supplementary information without interrupting the main flow of your documentation.

Overview

The footnotes extension provides:

• Reference-style footnotes - Define once, reference anywhere
• Inline footnotes - Quick notes without separate definitions
• Multiple references - Reference the same footnote multiple times
• Rich content - Include formatted text, lists, and code blocks
• Automatic numbering - Let Markdown handle the numbering
• Accessible markup - Semantic HTML with ARIA attributes

Configuration

Enable footnotes in your mkdocs.yml:

markdown_extensions:
  - footnotes

Basic Usage

Simple Footnotes

Create a footnote reference with [^label] and define it with [^label]: definition:

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

[^1]: This is the footnote definition.

Result:

This is a statement that needs a citation¹.

Multiple References

Reference the same footnote multiple times:

First reference[^note] and second reference[^note].

[^note]: This footnote is referenced twice.

Result:

First reference² and second reference².

Inline Footnotes

Create footnotes inline without separate definitions:

Here's an inline footnote^[This is defined right in the text].

Result:

Here's an inline footnote^[This is defined right in the text].

Advanced Usage

Multi-paragraph Footnotes

Include multiple paragraphs in a footnote:

Complex topic[^multi].

[^multi]: This is the first paragraph of the footnote.

    This is the second paragraph. Note the indentation.

    This is the third paragraph.

Result:

Complex topic³.

Footnotes with Lists

Include lists in footnotes:

See the requirements[^list].

[^list]: The following items are required:

    - Python 3.8 or higher
    - MkDocs 1.5.0 or higher
    - Material theme 9.0 or higher

    Make sure all dependencies are installed.

Result:

See the requirements⁴.

Footnotes with Code

Include code blocks in footnotes:

Example implementation[^code].

[^code]: Here's how to implement it:

    ```python
    def calculate(x, y):
        return x + y
    ```

    Call it with `calculate(5, 3)`.

Result:

Example implementation⁵.

Footnotes with Links

Include links in footnotes:

See the official documentation[^docs].

[^docs]: Visit [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) for more information.

Result:

See the official documentation⁶.

Styling

CSS Classes

Footnotes generate the following CSS classes:

• .footnote - The footnote reference link
• .footnote-ref - The reference number
• .footnote-backref - The back reference arrow
• .footnotes - The footnote definitions container

Custom Styling

Add custom styles for footnotes:

/* Footnote references */
.md-typeset .footnote {
  color: var(--md-primary-fg-color);
  font-weight: bold;
}

/* Footnote definitions */
.md-typeset .footnotes {
  font-size: 0.85rem;
  border-top: 1px solid var(--md-default-fg-color--lightest);
  margin-top: 2rem;
  padding-top: 1rem;
}

/* Hover effect */
.md-typeset .footnote:hover {
  color: var(--md-accent-fg-color);
}

Best Practices

1. Descriptive Labels

Use meaningful labels for footnotes:

✅ Good:
[^python-docs], [^rfc7231], [^smith2023]

❌ Bad:
[^1], [^a], [^footnote]

2. Placement

Place footnote definitions near their first reference:

✅ Good:
First paragraph with reference[^ref1].

[^ref1]: Definition immediately after paragraph.

Second paragraph continues...

3. Content Guidelines

Keep footnotes concise and relevant:

✅ Good:
[^version]: Requires Python 3.8 or higher

❌ Bad:
[^version]: This requires Python 3.8 or higher because...
[500 words of explanation]

4. Academic Citations

Use consistent citation format:

Recent studies[^johnson2023] show improved performance.

[^johnson2023]: Johnson, A. et al. (2023). "Performance
    Improvements in Documentation Systems." *Tech Journal*,
    45(3), 123-145. DOI: 10.1234/tj.2023.45.3.123

Common Patterns

References Section

Group all footnotes at the end:

## Main Content

Various claims[^1] and statements[^2] with evidence[^3].

## References

[^1]: First source
[^2]: Second source  
[^3]: Third source

Glossary Integration

Combine with definition lists:

API[^api-note]
:   Application Programming Interface

[^api-note]: See RFC 2616 for HTTP API standards

Citation Styles

Different citation formats:

APA Style[^apa]:
[^apa]: Smith, J. (2023). *Title*. Publisher.

MLA Style[^mla]:
[^mla]: Smith, John. *Title*. Publisher, 2023.

Chicago Style[^chicago]:
[^chicago]: Smith, John. *Title*. City: Publisher, 2023.

Integration with Other Features

With Admonitions

!!! note "Important[^note-ref]"
    This admonition includes a footnote reference.

[^note-ref]: Additional context for the note

With Tables

Feature	Version7	Status
Python	3.8+	Required
MkDocs	1.5+8	Required

With Code Annotations

def process(data):  # Process the data[^process]
    return result

# [^process]: Uses advanced algorithm

Accessibility

Footnotes include proper ARIA attributes:

<!-- Reference -->
<sup>
  <a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a>
</sup>

<!-- Definition -->
<li id="fn:1" role="doc-footnote">
  <p>Footnote text
    <a href="#fnref:1" class="footnote-backref"
       role="doc-backlink">↩</a>
  </p>
</li>

Troubleshooting

Common Issues

1. Undefined references: Ensure all [^label] have corresponding [^label]: definitions
2. Formatting breaks: Maintain consistent indentation in multi-line footnotes
3. Numbering issues: Let Markdown handle numbering automatically
4. Missing footnotes: Check for typos in labels

Debug Tips

Enable verbose output to debug footnote issues:

plugins:
  - search:
      verbose: true

Examples

Documentation with Citations

MkDocs uses Python[^python] for its build system. The
Material theme[^material] adds extensive features. Version
9.0[^v9] introduced significant improvements.

[^python]: Python Software Foundation. python.org
[^material]: Created by Martin Donath. MIT licensed.
[^v9]: Released January 2024 with 50+ new features.

Tutorial with Notes

## Installation

Install MkDocs[^install] using pip:

```bash
pip install mkdocs-material

Configure your site¹⁰ in mkdocs.yml.

See Also

• Python-Markdown Footnotes
• Definition Lists
• Abbreviations
• Academic Writing Guide

---

1. This is the footnote definition. ↩

2. This footnote is referenced twice. ↩↩

3. This is the first paragraph of the footnote.

   This is the second paragraph. Note the indentation.

   This is the third paragraph. ↩

4. The following items are required:

   • Python 3.8 or higher
   • MkDocs 1.5.0 or higher
   • Material theme 9.0 or higher

   Make sure all dependencies are installed. ↩

5. Here's how to implement it:

   def calculate(x, y):
       return x + y
   

   Call it with calculate(5, 3). ↩

6. Visit Material for MkDocs for more information. ↩

7. Minimum supported versions ↩

8. Material theme requires MkDocs 1.5.0 ↩

9. Requires Python 3.8+. Use virtual environment. ↩

10. See configuration guide for all options. ``` ↩