Obscure warning when heading directly preceded by footnotes

[rossbar]

Describe the bug

When trying build a document via sphinx that ends with a heading, I see the following warning:

foo.md:0: WARNING: Document or section may not begin with a transition.

The warning makes it seem like there was a problem parsing the metadata at the front of the file, when the problem is (or seems to be, anyway) that the file ends with a heading.

To Reproduce

I noticed this when trying to build files that had heading to denote the footnotes or references. For example:

# My article                                                                    
                                                                                
Here's my footnote [^1].                                                        
                                                                                
## Footnotes                                                                    
                                                                                
[^1]: my footnote.

This file was included in a project using the myst_nb sphinx extension, and the warning above would appear during the sphinx build process.

If you delete the ## Footnotes, the warning disappears, so my hypothesis was that the myst-parser doesn't allow you to end documents with headings.

Expected behavior

Either allow a document to end with headings, or explicitly catch the "document's shouldn't end with a heading" pattern and raise an error/warning with a specific message to that effect.

Environment

• Python Version: 3.9.3
• Package versions or output of jupyter-book --version:
  • myst_nb: 0.12.0
  • myst_parser: 0.13.6
• Operating System: Linux

Additional context

I wasn't sure if this should be reported to myst_nb or here, but in the end it seemed like the root cause was something to do with the markdown parsing. If not, please feel free to transfer the issue to a more appropriate repo. If there are problems transferring, LMK and I'd be happy to close this and open a new issue elsewhere.

[chrisjsewell]

Heya, its not just that it ends with a heading, its because the heading is directly followed by the footnotes that by default are preceded by a transition (i.e. a line ---).
Add myst_footnote_transition = False to your conf.py to remove the transition and the warning should dissapear 😄

[chrisjsewell]

It would be difficult to exactly check for this scenario during parsing (and IMO you shouldn't really be using a headings for footnotes 😬), so I think just noting this in the documentation may need to suffice

[rossbar]

Add myst_footnote_transition = False to your conf.py to remove the transition and the warning should dissapear smile

Thanks for the explanation :)

I think just noting this in the documentation may need to suffice

Agreed about a note in the documentation. I might also go one step further and advocate for a change in the default value for myst_footnote_transition. The reason being that the injection of the transition isn't explicit, so even after spending 10's of minutes on this warning, it was difficult for me to track down what was happening (and of course even after that I didn't get it nailed down correctly).

This actually came up in our project not from footnotes, but from our intentional abuse of the footnote syntax for setting up references for a single html page. I've also seen the [^#] syntax used in the wild for citations in other markdown flavors and extensions, so while this is a corner case and understandably not something you want to encourage, I would imagine it won't be the only case where an author does something along the lines of:

## References

[^1]: ...

and runs into this problem.

Just a thought though - I certainly understand the aesthetic argument for including the transition by default (it does look nice!)

[chrisjsewell]

Thanks for the feedback 👍

[zakgrin]

Two bad things (1 Error and 1 warning) appear by myst.footnote specifically in markdown (.md) files and in markdown cells in .ipynb files when you use footbibliography.

1. Warning: WARNING: No footnote definitions found for label: '' [myst.footnote]

To solve this warning, you just need to suppress this warning by adding the following code to your conf.py file:

suppress_warnings = [
...
"myst.footnote",
]
`

2. ERROR: Document may not end with a transition.

This is also another issue when you add the directive footbibliography to a notebook. Removing/adding a header or some text before or after this directive did not solve the issue for me. So I had to myst_footnote_transition = False.