Skip to content

Flag to not move footnotes #34

Description

@ioggstream

Context

Given

### Footnote

Here's a sentence with a footnote. [^1]

[^1]: This is the footnote.

## Whatever

Other stuff

When

mdformat-footnote --new-flag-for-not-relocating-footnotes

I expect

  • Unchanged, footnote still close to the original text.
### Footnote

Here's a sentence with a footnote. [^1]

[^1]: This is the footnote.

## Whatever

Other stuff

Instead

  • Footnote is moved at the end of the document
### Footnote

Here's a sentence with a footnote. [^1]


## Whatever

Other stuff

[^1]: This is the footnote.

Proposal

A new flag --keep-footnote-position
that does not move footnotes at the EOF

Tasks and updates

No response

Activity

  1. self-assigned this
    on Sep 1, 2026
  2. KyleKing commented on Sep 1, 2026

    @KyleKing
    Collaborator

    I have two open PRs that should do most of what you might want, but there are edge cases that are just really hard to work around. Let me know if this looks good and this is a demo:

    mdformat --keep-footnote-position demo-keep-footnote-position.md

    # `--keep-footnote-position` demo
    
    ## Happy path
    
    This package uses [flit](https://flit.readthedocs.io) as the build engine.[^flit]
    
    [^flit]: Flit only understands `pyproject.toml`-based packages, no `setup.py` fallback.
    
    `--keep-footnote-position` leaves `[^flit]` right where it is. Default mode would move
    it to the end of the document instead.
    
    An unreferenced definition is still dropped by default, same as normal mode:
    
    [^unused]: Nobody points to this one.
    
    ## Preserves position, doesn't infer one (Limitation)
    
    The flag only stops mdformat from *moving* definitions; it doesn't relocate one to sit
    near its reference if the source didn't already put it there.
    
    Two more notes.[^one] And a third.[^two]
    
    [^one]: Written in the traditional trailing style.
    
    [^two]: Same convention, same result either way.
    
    ## Limitation: a duplicate label keeps both definitions
    
    Default mode silently keeps only the *last* definition of a repeated label, discarding
    the first. `--keep-footnote-position` keeps both, since nothing merges them anymore:
    
    Referenced once.[^dup]
    
    [^dup]: First definition.
    
    [^dup]: Second definition for the same label.

    What do you think of #44 and #45? Would they address your request?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions