Skip to content

Footnotes are squished together by rustdoc when there's no empty line between them #100638

New issue
New issue
Closed
#120443
Closed
Footnotes are squished together by rustdoc when there's no empty line between them#100638
#120443
Labels
A-rustdoc-uiArea: Rustdoc UI (generated HTML)C-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Description

@CJKay
CJKay
opened on Aug 16, 2022

Problem

Footnote lines, when written on adjacent lines, squish into a single footnote:

//! [^1]: Footnote A.
//! [^2]: Footnote B.
//! [^3]: Footnote C.

Screenshot 2022-08-16 at 18 39 09

Steps

  1. Copy-paste the following snippet at the top of a new module:

    //! Reference to footnotes A[^1], B[^2] and C[^3].
//!
//! [^1]: Footnote A.
//! [^2]: Footnote B.
//! [^3]: Footnote C.

  2. Run cargo doc.

  3. Observe that the footnotes have been incorrectly rendered as a single footnote.

Possible Solution(s)

No response

Notes

One workaround is to separate the footnotes with empty lines:

//! [^1]: Footnote A.
//! 
//! [^2]: Footnote B.
//! 
//! [^3]: Footnote C.

It's not pretty, though.

Version

cargo 1.64.0-nightly (b1dd22e66 2022-07-09)
release: 1.64.0-nightly
commit-hash: b1dd22e668af5279e13a071ad4b17435bd6bfa4c
commit-date: 2022-07-09
host: x86_64-apple-darwin
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.79.1 (sys:0.4.55+curl-7.83.1 system ssl:(SecureTransport) LibreSSL/3.3.6)
os: Mac OS 12.5.0 [64-bit]

Activity

  1. ImageCJKay
    added
    C-bugCategory: This is a bug.
    on Aug 16, 2022

  2. Eh2406 commented on Aug 16, 2022

    @Eh2406
    Eh2406
    on Aug 16, 2022
    Contributor

    Transferring to Rust as it is an issue with doc generation.

  3. ImageEh2406
    transferred this issue fromrust-lang/cargoon Aug 16, 2022

  4. ehuss commented on Aug 16, 2022

    @ehuss
    ehuss
    on Aug 16, 2022
    Contributor

    I think this is somewhat working as intended. Footnote definitions need to be separated by blank lines.

    That is not ideal, and I think pulldown-cmark/pulldown-cmark#20 is the closest thing tracking this issue.

  5. GuillaumeGomez commented on Aug 23, 2022

    @GuillaumeGomez
    GuillaumeGomez
    on Aug 23, 2022
    Member

    This is the expected behaviour from commonmark as you can see here.

    Closing then.

  6. ImageGuillaumeGomez
    closed this as completedon Aug 23, 2022

  7. CJKay commented on Aug 23, 2022

    @CJKay
    CJKay
    on Aug 23, 2022
    Author

    This is the expected behaviour from commonmark as you can see here.

    Closing then.

    Hi @GuillaumeGomez, CommonMark does not support footnotes at all. RustDoc is very explicit that it does, so the behaviour of RustDoc's footnotes should probably be based on whatever library it uses for Markdown parsing rather than actual CommonMark.

    You can see from this simple example that CommonMark does not support footnotes:

    Reference to footnote A[^1].

[^1]: Footnote A.
    <p>Reference to footnote A[^1].</p>
<p>[^1]: Footnote A.</p>

    But CommonMark with "extensions" does:

    <p>Hello, World<a href="#fn1" class="footnote-ref" id="fnref1"
role="doc-noteref"><sup>1</sup></a>!</p>
<section id="footnotes" class="footnotes footnotes-end-of-document"
role="doc-endnotes">
<hr />
<ol>
<li id="fn1"><p>The world is big!<a href="#fnref1" class="footnote-back"
role="doc-backlink">↩︎</a></p></li>
</ol>
</section>

  8. GuillaumeGomez commented on Aug 23, 2022

    @GuillaumeGomez
    GuillaumeGomez
    on Aug 23, 2022
    Member

    Oh I see, my apologies. Reopening the issue then.

  9. ImageGuillaumeGomez
    reopened this on Aug 23, 2022
  10. ImageChrisDenton
    added
    needs-triage-legacy
    on Jul 16, 2023
  11. Imagefmease
    added
    T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
    A-rustdoc-uiArea: Rustdoc UI (generated HTML)
    and removed
    needs-triage-legacy
    on Jan 25, 2024
  12. Imagefmease
    changed the title [-]Footnotes are squished together by `cargo doc` when there's no empty line between them[/-] [+]Footnotes are squished together by rustdoc when there's no empty line between them[/+] on Jan 25, 2024

  13. fmease commented on Jan 25, 2024

    @fmease
    fmease
    on Jan 25, 2024
    Member

    Triage: Still an issue.

  14. GuillaumeGomez commented on Jan 26, 2024

    @GuillaumeGomez
    GuillaumeGomez
    on Jan 26, 2024
    Member

    Taking a look.

  15. ImageGuillaumeGomez
    added 2 commits that reference this issue on Jan 28, 2024

    Add regression test for rust-lang#100638

    aa71c7c

    Add regression test for rust-lang#100638

    dad6802
  16. Imagematthiaskrgr
    added a commit that references this issue on Jan 28, 2024

    Rollup merge of rust-lang#120443 - GuillaumeGomez:footnote-def-improv…

    1ff326d
  17. Imagefmease
    added a commit that references this issue on Jan 29, 2024

    Rollup merge of rust-lang#120443 - GuillaumeGomez:footnote-def-improv…

    83b3958
  18. ImageGuillaumeGomez
    added 2 commits that reference this issue on Jan 29, 2024

    Add regression test for rust-lang#100638

    1e60cc9

    Rollup merge of rust-lang#120443 - GuillaumeGomez:footnote-def-improv…

    f35504d
  19. Imagebors
    closed this as completedin f35504don Jan 30, 2024
  20. Imagerust-timer
    added a commit that references this issue on Jan 30, 2024

    Unrolled build for rust-lang#120443

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-rustdoc-uiArea: Rustdoc UI (generated HTML)C-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions