I consider that it would be quite useful to have footnotes as they work in Markdown. In fact the syntax for Markdown is usually the following:

This is normal text containing a note[^nameOfYourFootnote]. You can write as much as you need.

In this case, if you click you will be directed to the location where the note is located (but you can go back to reading point easily).

That generates the following:

This is normal text containing a note¹. You can write as much as you need.

In this case, if you click you will be directed to the location where the note is located (but you can go back to reading point easily).

1. Here will be the text of your note.

I know it can be done with HTML directly, but in Markdown it saves a lot of work.

1. [^ nameofyourfootnote ]

   Here will be the text of your note.

+1

It would also be very practical that the footnotes included backlinks as in Wikipedia and also a preview when passing the pointer on these as it happens in Wikidot

+1

Fossil friend George has started work towards this in the markdown-footnotes branch.

I'll be honest, I would have thought we would have seen tags for forum posts and wiki posts before this request, but I welcome any improvements!

I like footnotes a lot, maybe overly so. And having used them a lot, I know they can be a pain to do right when the footnote text is separated from the footnote reference in the source text. (It's too easy to forget or delete one and not the other.)

So I would suggest an input form such as:

 This text is footnoted[^Yes, it truly has a footnote!].

This has the added advantage of not needing a name to link the footnote reference to its content.

For what it's worth, the markdown-based note taking utility Obsidian uses this format:

This text is footnoted^[Yes, it truly has a footnote!].

It seems to make more sense to me, for whatever reason. And in any case, when introducing non-standard syntax, it is perhaps better to use non-standard syntax that others already use, in the hopes that it will become standard one day. ;-)

I could not agree more. My itch is to get it done in one fell swoop instead of a pair of objects that have to track each other. Further, I prefer that Obsidian syntax.

get it done in one fell swoop

Indeed. Though to be fair, one of the design criteria of markdown is that the plain markdown code should be almost as readable as the formatted version. In which case, the split format makes sense. But if that is not important, get it done and over with.

Thanks to everyone for the comments.
Please take a look at the corresponding wiki page and help decide on the syntax. For the time being, I lean towards the first variant in every category.

Please take a look at the corresponding wiki page and help decide on the syntax.

FWIW, my strong preference is what you refer to as "referenced free-standing"¹. That seems to follow markdown's human-readability goals best and seems to me to be easiest to write. It also closely follows a syntax many people already use for footnotes.

1. ^{^} having footnotes inlined is essentially identical to using parenthesis to extend a thought (and we don't need any new syntax for that (IMO)). Since a reader of unprocessed markdown has to read inlined footnotes in order to get past the "footnote" (which isn't at the foot at all), there would seem to be little benefit over using plain parenthesis for such things. Referenced free-standing doesn't suffer from those questionable qualities.

Thanks, George, for promoting and pushing this feature. Please excuse me for giving short shrift to syntax, which I am sure will be something reasonable and usable. These considerations also merit attention, IMO:

An inline footnote need not be the same distraction in the markdown source as its text would be if just inlined (without use of a footnote.) For example, leveraging long-standing practice for nroff/troff input: This is a multi-clause sentence, written as a demonstration1 of keeping inline footnotes from being confounded with the text in which their references appear. . As can be seen, before that text is flowed to obscure the structure in that input, the inline footnote can be kept visually distinct from the main text, and the main text can be read with little attention given to mentally parsing out the footnote. Hence, input source clarity need not weigh against supporting inlined footnotes.

The ability to inline a footnote and reference its text in another footnote reference would alleviate the tension raised regarding tradeoffs between inlined and separated footnote forms. This option, even if not implemented at first, may affect syntax choices. (Maybe there should be no dichotomy between inlined and separated forms.)

John Gruber at Daring Fireball brings up an attention-worthy issue and a mitigation for it, relating to where the footnote text is placed and how readers can conveniently attend both footnote text and the text in which the footnote is referenced. Inked-words-on-paper producers have dealt with this issue by using both "footnotes" and "endnotes". For web pages, I think those map to "below present paragraph" and "at end of present page". However, a third option exists for browser display: a small, hover-triggered pop-up which vanishes on its own when the pointer leaves the footnote reference. (In GUI design, this is sometimes referred to as "tool tips".) Regardless of which placements you might support, addressing the footnote text placement and navigation issues well will make the difference between a cool technical feature and something that really aids readers of the processed results. (I do not pretend to have answers here, but offer this for discussion and thought.)

1. ^{^} The demo's purpose is irrelevant here.

However, a third option exists for browser display: a small, hover-triggered pop-up which vanishes on its own when the pointer leaves the footnote reference.

That part's trivial to do if the footnotes have a distinct CSS class we can select them with. We do this for tooltips in all of the ajax-centric apps, but we do it on click instead of hover, largely for consistency with mobile platforms. See /pikchrshow for an example: look for the blue circles with a question mark in them. One notable limitation, though: if the footnote is large enough, the tooltip becomes larger than the browser's viewport.

I'd like to vote for a non-JS solution.

I often print web pages, occasionally to paper for offline reading, but more often to PDF for archiving, or for reading on a simple Ebook Reader device. So I'd appreciate to get complete documents, without having to click anything, first.

(I like the simple style of the SQLite web sites, but their minimal fanciness can already hinder usability: printing the SQLite Documentation Index is cumbersome, and requires clicking each ► arrow to unfold it's content, first.

I was looking for a quick example -- it's less the ► TOC arrows, but more the show/hide buttons for the SQL syntax diagrams that make is cumbersome to get PDFs of complete SQLite documentation web pages, with all information visible.

requires clicking each ► arrow to unfold it's content, first

Well, I haven't printed a Web page in a long while.
But in the olden days, on Chrome, it would open a separate page on Chrome,
one where printing-specific stylesheet(s) were used.

HTML support that use case already, to have different looks for screens and printed pages.
So maybe the problem is SQLite (or Fossil) not offering that dual nature?

Print and screen specific stylesheet would allow both use cases.

So maybe the problem is SQLite (or Fossil) not offering that dual nature? Print and screen specific stylesheet would allow both use cases.

The sqlite docs are generated using other tools with only a single skin, so that one would possibly be feasible to support print mode for, but that's a topic for the sqlite doc maintainers (at least two of them closely follow this forum).

Fossil, however, would very likely require print-mode CSS for each and every one of its skins. Feel free to write, test, and contribute those ;).

I don't think the details element (assuming that is being used) can be opened using CSS. It should be openable using js. A one button click before printing to display all details. But at least you only have to click once rather than finding and clicking every element.

I have scripts to automate web browsers to print a list of URLs to PS files, and combine them into one single PDF. This is handy to generate "one-page" manuals (easy to search), or simply to archive web pages.

But not only in this context do I consider web pages that require to "click once" to see all contents an annoyance.

Coincidentally, my favorite blog had a post just yesterday with footnotes within footnotes ;-)

https://devblogs.microsoft.com/oldnewthing/20220204-00/?p=106219

IMO, the core functionality of footnotes is mostly implemented.

You may look at the rendering of a test document. The syntax is documented here.
Please say how do you like the overall look and functionality.

JavaScript is not involved in the current implementation, but the proper functioning of <a href="#fragment">...</a> hyperlinks is required. This is the case for the /doc pages as shown via the above link. However most other pages (including the /forumpost) are malfunctioning because <base href="..."> element in the header contains truncated URL that does not match the URL in a browser's address bar. I suggest that the later should be fixed. What do you think?

George, I'm so happy to see this and eager to use it that I can hardly think straight enough to come up with some niggling criticism. It looks like you have put a lot of thought into this. I especially like the back-and-forth navigation action between footnotes and their references. Superb!

The broken link red highlite is nice. I hope there is some other route for the fact of such brokeness to reach somebody working on a doc with footnotes, so that scanning alone is not required. An error exit status returned during a build, or some obvious big-bad-red-notice at the top of page might work if there is no command-line driven build process.

You may look at the rendering of a test document. The syntax is documented here.

Wow. You did an amazing job on that, far beyond any hopes i had for footnote support. i'm looking forward to using this. Like Larry, i tend to make heavy use of footnotes in my docs.

... contains truncated URL that does not match the URL in a browser's address bar. I suggest that the later should be fixed. What do you think?

It sounds like the base href needs to be fixed, but changing that may have unintended side effects so it needs to be checked carefully.

Larry and Stephan, thank you very much for kind words!

Branch base-href-fix should now enable proper handling of "#fragment" hyperlinks (and the footnotes in particular) within forum, tickets and wiki (and almost anywhere else, including the Sandbox).

The /fileedit and /info for the embedded docs continue to override base href. It is not clear to me if (and how) this should be changed. I suggest that it is left the way it is now (at least for a while).

I invite interested Fossil users to test these two features using this mirror of the Fossil project and share the experience. Cases where a hyperlink is broken at the mirror but works fine at the upstream are of particular interest. Thank you in advance.

The /fileedit and /info for the embedded docs continue to override base href. It is not clear to me if (and how) this should be changed. I suggest that it is left the way it is now (at least for a while).

My recollection is that /fileedit has to swap out the baseref when it's in the preview tab in order for the links in the preview to work. It records the page's original baseref and restores it when the preview tab is hidden.

See code comments here.

My suggestion is also to leave that one for now unless it's causing you any specific problems, in which case we can address them.

I invite interested Fossil users to test these two features using this mirror of the Fossil project and share the experience.

FWIW: in my basic tests it "works for me," but i'm quite certain, based on your commit history, that your own testing has been far more extensive.

I would like footnotes to be merged into trunk.
It works for the embedded documentation and other pages that don't mess with base href.

I tried to tackle base href issue twice: for the first time on a separate branch and for the second time by prepending #fragments in relative hyperlinks with the REQUEST_URI of a page being served.
The former approach was considered as over-complicated and was not accepted and the later does not resolve the issue completely (e.g. for /wikiedit page).

I think that base-href issue is somewhat independent from the footnotes and may be tackled afterwards.

I would like footnotes to be merged into trunk.

As would Larry and myself :). i'll give the code a thorough review today and/or tomorrow and either make any necessary changes or provide feedback about them.

It works for the embedded documentation and other pages that don't mess with base href.

AFAIK only the /wikiedit and /fileedit preview modes change the base-href, unfortunate special cases required for fixing links in previews because their URL path in the editor is different from the path the docs are written for. i'll have to experiment to figure out why/whether /wikiedit really needs that - it possibly doesn't. /fileedit does, though, for any relative-path links to work in preview mode.

I think that base-href issue is somewhat independent from the footnotes and may be tackled afterwards.

Agreed.

i'll give the code a thorough review today and/or tomorrow and either make any necessary changes or provide feedback about them.

@George,

i've gone through the footnotes code, made some cosmetic style tweaks, fixed a few typos, and resolved the (cosmetic) TODOs related to the BLOB_xxx macros. The only two open points i have are:

• markdown_html.c's bitfield64_t: i didn't feel comfortable documenting its members and ask that you please do so. (Please update to the tip first!)
• The purpose of the FOOTNOTES_WITHOUT_URI option should probably be obvious, giving its descriptive name, but it's not clear to me what that's for and whether it's necessary.

Other than that: you've done an outstanding job and gone well "above and beyond" any base requirements for footnotes. The lint-related features are a big bonus and should prove very helpful to "doc fanatics" such as myself and Larry.

Thank you very much! Please find comments in check-in cf1e96918edc.
I usually define FOOTNOTES_WITHOUT_URI macro for my local builds (which also incorporate base-href-fix branch).

Please find comments in check-in cf1e96918edc.

FWIW, it looks good to me!

I usually define FOOTNOTES_WITHOUT_URI macro for my local builds (which also incorporate base-href-fix branch).

We can address that (separate) issue later on. It only affects the edit-mode previews and my current suspicion (untested) is that /wikiedit doesn't need the same workaround which /fileedit requires because wiki pages all live under the same URI (mostly... branch- and checkin-specific pages can be rendered from different paths, e.g. /timeline).

Support for footnotes has been merged into trunk.
I invite everyone to try it and report any issues.

Stephan and I have done some fuzz testing of 0850862e6a2a as described in the docs.
I'll continue fuzz testing of 3990518b296a for at least a couple of days.

Many thanks to all for feedback, advice and support!

This is normal text containing a note...

@George: looking at the top-most post of this thread, it seems we have our first bug report: inside of a code block, footnotes should not be parsed. In this case, a footnote inside of a code block is showing up as a "defined but not referenced" footnote.

Edit: CORRECTION. i didn't read the rest of the post, where that same footnote is indeed included.

This very first post might become the endless source of confusion :-)
It was written before any footnote support was implemented. The OP includes a hand-written #fragment hyperlink which looks like automatically generated footnote but actually didn't work at the moment of writing and will remain broken until "base href" is fixed.