mdformat-footnote

Common errors

• Error: Could not format "/path/to/your_file.md". The formatted Markdown renders to different HTML than the input Markdown. This is likely a bug in mdformat. Please create an issue report here...

  cause This error often occurs when `mdformat` (or a plugin like `mdformat-footnote`) encounters Markdown syntax it cannot correctly parse or format without changing the semantic meaning of the document. For footnotes, this might indicate an issue with how the plugin is interpreting or reordering them, or a conflict with other extensions.
  fix First, ensure `mdformat-footnote` is installed and the 'footnote' extension is enabled. If the problem persists, try isolating the footnote-related content to confirm it's an `mdformat-footnote` issue. The `mdformat` core maintainers fixed similar issues in early versions of `mdformat-footnote` (e.g., Issue #6), so upgrading to the latest version might resolve it. If the issue is with 'orphan' footnotes (definitions without references), consider using the `--keep-footnote-orphans` CLI option or `keep_orphans=True` in the API.

• mdformat: error: unrecognized arguments: --footnote

  cause The `--footnote` argument is not a valid way to enable the `mdformat-footnote` plugin. `mdformat` uses a generic `--extensions` flag for all parser extension plugins.
  fix Use the `--extensions` flag with the value `footnote`. Correct CLI usage is: `mdformat --extensions footnote your_file.md`.

• ModuleNotFoundError: No module named 'mdformat_footnote'

  cause The `mdformat-footnote` package is not installed in the current Python environment or is not accessible to `mdformat`.
  fix Install the package using pip: `pip install mdformat-footnote`. If using `pipx`, ensure it's injected into the `mdformat` virtual environment: `pipx inject mdformat mdformat-footnote`.

Warnings

• breaking mdformat-footnote v0.1.2 upgraded to support mdformat v1 and Python >=3.10. Older versions of mdformat-footnote will not work with mdformat v1+ or Python versions below 3.10.
  Fix: Upgrade mdformat-footnote to 0.1.2 or later: `pip install --upgrade mdformat-footnote`. Ensure your Python environment is 3.10 or newer.
• gotcha mdformat is a CommonMark formatter. Without the `mdformat-footnote` plugin enabled, any footnote syntax will be treated as non-CommonMark and may be backslash-escaped or otherwise incorrectly handled, leading to a loss of intended Markdown structure.
  Fix: Always enable the 'footnote' extension when you intend to format documents containing footnotes, either via the CLI (`mdformat --extensions footnote your_file.md`) or Python API (`mdformat.text(..., extensions={'footnote'})`).
• gotcha The `mdformat` core documentation recommends pinning `mdformat` dependency versions because its formatting style may change in each version. This also applies to `mdformat-footnote` and could lead to unexpected reformatting.
  Fix: Pin your `mdformat` and `mdformat-footnote` versions in your `requirements.txt` or `pyproject.toml` (e.g., `mdformat==1.0.0`, `mdformat-footnote==0.1.3`) to ensure consistent formatting across runs and environments.

Install

• pip install mdformat mdformat-footnote Install with pip
• pipx install mdformat pipx inject mdformat mdformat-footnote Install with pipx (recommended for CLI)

Imports

• mdformat
  wrong:

  from mdformat_footnote import FootnotePlugin

  correct:

  import mdformat
  # No direct import for mdformat_footnote's plugin module is typically needed for userland code, as mdformat loads it.

  mdformat-footnote is loaded by mdformat as an extension, not typically imported directly in application code. You enable it via mdformat's 'extensions' argument or CLI flag.

Quickstart

To use `mdformat-footnote`, you need to install both `mdformat` and `mdformat-footnote`. Then, when using `mdformat` (either via the Python API or CLI), you must explicitly enable the 'footnote' extension.

import mdformat

markdown_with_footnotes = (
    """
Here is a footnote reference.[^1]

And here's a longer one.[^bignote]

[^1]: This is the first footnote.
[^bignote]: Here's one with multiple paragraphs and code.
    
    Subsequent paragraphs are indented to show that they belong to the previous footnote.
"""
)

# Using the Python API to format with the footnote extension
formatted_markdown = mdformat.text(markdown_with_footnotes, extensions={'footnote'})

print("--- Original ---")
print(markdown_with_footnotes)
print("\n--- Formatted ---")
print(formatted_markdown)

# To use via CLI (assuming mdformat and mdformat-footnote are installed):
# Save the above markdown to a file, e.g., 'input.md'
# Then run: mdformat --extensions footnote input.md