search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
18.23k stars 1.63k forks source link

Ordering of footnote #2409

Open harryhanYuhao opened 4 months ago

harryhanYuhao commented 4 months ago

Problem

Currently the footnotes are numbered by their first reference in text, instead of the actual order of the footnote in the end.

For example 

aha[^note], that is right[^another_note]

[^another_note]: right
[^note]: aha

Will be rendered to something like

aha^1, that is right^2

2 right
1 aha

Notice the footnote numbered as 2 is placed first. This is both unnatural and non-customary.

The customary style which is used by most journals is to number the footnotes in the order they are presented at the end.

aha[^note], that is right[^another_note]

[^another_note]: right
[^note]: aha

shall produce

aha^2, that is right^1

1 right
2: aha

Proposed Solution

Number the footnotes by their orders at the end, as most journals do.

Notes

No response

chriskrycho commented 3 months ago

The latest version of pulldown-cmark (0.11) supports this, although it requires doing a bit of rewriting of the event stream. The example linked there is pretty well-commented! To make it work in mdbook, you would probably need to change the new_cmark_parser API. It and the output from its neighbors render_markdown and render_markdown_with_path are public API, and this would also substantially change their output, so this would need to either be a breaking change or an additional option.

Related: #2401, which would also enable a more standard form of footnote parsing (you can fix the rendering with the old or the new parsing).