search

gettalong / kramdown

kramdown is a fast, pure Ruby Markdown superset converter, using a strict syntax definition and supporting several common extensions.
http://kramdown.gettalong.org
Other
1.72k stars 271 forks source link

Syntax Documentation and Footnotes #339

Closed digitalgutenberg closed 8 years ago

digitalgutenberg commented 8 years ago

Hi there!

The fact that footnotes can be placed anywhere in the text, isn’t mentioned in the syntax documentation even if it has been a feature since 2014: https://github.com/gettalong/kramdown/commit/8efa9c30c45014442970d5976dd0e0005682edf3

I suppose this is an oversight? In my opinion, this feature is important and very useful, there are some important scenarios where moving the footnotes to the end of the document is an unwanted behavior.

Cheers, Wilfred

gettalong commented 8 years ago

If you look at the commit you mention, it explicitly states there that the location of the footnotes can be customized by using a list and the special reference name "footnotes" - https://github.com/gettalong/kramdown/commit/8efa9c30c45014442970d5976dd0e0005682edf3#diff-d7c7ec0a82a37893bb48b1c6ee017f67R119

digitalgutenberg commented 8 years ago

Well yes, exactly, and this is obviously why I linked to the commit!

I apologize if I was too unclear in my initial post. My point is that it isn't mentioned your official documentation found here: http://kramdown.gettalong.org/syntax.html (or in the doc/syntax.page)

The feature is documented in the commit, but this information is lacking from the documentation, which is the place people go if they want to learn about the use of kramdown.

gettalong commented 8 years ago

The reason for this is that this is a feature of the HTML converter and not the parser, therefore it is listed with the converter information which is also part of the official documentation.

digitalgutenberg commented 8 years ago

Thanks a lot for elaborating! My bad, yes, you’re right, it is mentioned in the converter documentation.

I do get your point, syntax = parser, right? The “syntax page” was the go-to place for a noob such as myself, this is the natural place to look for a random user trying to figure out a kramdown-related problem. But okay, I get it, I understand that the parser and the converter are completely different things, my apologies!

Anyways, thank you for bothering to reply and for your hard work with kramdown!

Have a nice day!

P.S. The example in test/testcases/span/04_footnote/placement.text was actually extremely helpful for me when it comes to actually understanding what it means to add “the special reference name "footnotes"” to an ordered or unordered list. Sometimes it helps to see a visual example.