Please support markdown footnotes [^1] [^note]

thediveo commented 3 years ago

Feature request

What problem does this feature solve?

Footnotes allow you to add notes and references without cluttering the body of the document.

For instance, in docsified software manuals this would help with structuring the information given better: useful background information can be given and clearly linked with the main text, yet without making the main text too full of details.

What does the proposed API look like?

According to the Markdown Guide:

A footnote[^1]

[^1] This is a footnote.

How should this be implemented in your opinion?

I'm not sure I understand this question in the context of this particular feature request.

One thing I notice it that docify authors might want to have control over the placement of footnotes: either at the end of a "page" or, alternatively, before the next same-level heading.

Are you willing to work on this yourself?

Unfortunately, I completely lack the necessary Javascript and markdown parsing experience to code this.

sy-records commented 3 years ago

We use marked, is "footnote" supported in marked.js?

if you want, you can put them all at the end of your document, sort of like footnotes.

Here's an example of reference links in action:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

Using the implicit link name shortcut, you could instead write:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

I get 10 times more traffic from Google than from Yahoo or MSN.

see https://github.com/markedjs/marked/blob/master/test/specs/original/markdown_documentation_syntax.md#span-elements

thediveo commented 3 years ago

@sy-records I appreciate your suggestion, but this is difficult to keep consistent in larger documents and lacks the chance of proper CSS styling (unless you add in convoluted HTML interspersed with markdown).

Looking more around the link you gave, I found this answer with code snippets of how to add that feature after marked parsing and before rendering: https://github.com/markedjs/marked/issues/1562#issuecomment-749652111

Unfortunately, I lack any experience in this area as to how marked is used in docsify and how to tap into the parsing and rendering. :(

thediveo commented 3 years ago

I've adapted https://github.com/markedjs/marked/issues/1562#issuecomment-749652111 to docsify's link handling as follows (not a plugin, that's out of reach for me):

  <script>
    const footnoteMatch = /^\[\^([^\]]+)\]:([\s\S]*)$/
    const referenceMatch = /\[\^([^\]]+)\](?!\()/g
    const referencePrefix = "marked-fnref"
    const footnotePrefix = "marked-fn"
    const footnoteTemplate = (ref, text) => {
      return `<sup id="${footnotePrefix}-${ref}" class="footnote-symbol">${ref}</sup><span class="footnote-text">${text}</span>`
    }
    const footnoteContainerTemplate = (text) => {
      return `<div class="marked-footnotes"><h4>References</h4>${text}</div>`
    }
    const referenceTemplate = (ref) => {
      return `<sup id="${referencePrefix}-${ref}" class="footnote-reference-symbol"><a href="${window.location.hash.split("?")[0]}?id=${footnotePrefix}-${ref}">${ref}</a></sup>`
    }
    const interpolateReferences = (text) => {
      return text.replace(referenceMatch, (_, ref) => {
        return referenceTemplate(ref)
      })
    }
    const interpolateFootnotes = (text) => {
      const found = text.match(footnoteMatch)
      if (found) {
        const replacedText = text.replace(footnoteMatch, (_, value, text) => {
            return footnoteTemplate(value, text)
        })
        return replacedText /* footnoteContainerTemplate(replacedText) */
      }
      return text
    }

    window.$docsify = {
      markdown: function (marked, renderer) {
        marked.setOptions({
          smartypants: true,
          renderer: Object.assign(renderer, {
            paragraph(text) {
              return marked.Renderer.prototype.paragraph.apply(null, [
                interpolateReferences(interpolateFootnotes(text))
            ])},
            text(text) {
              return marked.Renderer.prototype.text.apply(null, [
                interpolateReferences(interpolateFootnotes(text))
            ])},
          }),
        })
        return marked
      },
    ...
  </script>

needs an explicit "#### References" or similar, as it never sees the footnote text definition en bloc, but only as individual texts.
is there any way to add classes to the outer paragraph?
I can't get multiple paragraphs working in a single footnote definition working.

Any ideas?

onedge commented 2 years ago

I wrote some code to handle footnotes in the [^1] pattern. I hope this helps you.

index.html

plugins: [
        function(hook, vm) {
          hook.beforeEach(function(html) {
          ...
          // footnote
            if (/\[\^\d+\][^:]/.test(html)) {
              html = html
                .replace(/\[\^(\d+)\][^:]/gm, '<sup class="footnote-symbol" id="ft$1">[\[$1]\](#ftref$1)</sup>')
                .replace(/\[\^(\d+)\]\: /gm, '<strong class="footnote-reference-symbol" id="ftref$1">[\[$1\]](#ft$1)</strong>:leftwards_arrow_with_hook: ');
            }

example.md


 > Between people an island exists.  I want visit that island. [^1]

 ### Reference

 [^1]: Island by Jung Hyun-jong [(ref)](https://jaypsong.blog/2011/11/10/island-by-jung-hyun-jong/)

It looks like this.

Between people an island exists. I want visit that island. ¹

Reference

[1] Island by Jung Hyun-jong (ref)

If you want to process patterns like [^note] too, do this.

index.html

plugins: [
        function(hook, vm) {
          hook.beforeEach(function(html) {
          ...
          // footnote
            if (/\[\^\.+\][^:]/.test(html)) {
              html = html
                .replace(/\[\^(\.+)\][^:]/gm, '<sup class="footnote-symbol" id="ft$1">[\[$1]\](#ftref$1)</sup>')
                .replace(/\[\^(\.+)\]\: /gm, '<strong class="footnote-reference-symbol" id="ftref$1">[\[$1\]](#ft$1)</strong>:leftwards_arrow_with_hook: ');
            }

sy-records commented 2 years ago

Hi there. Thanks @onedge, I have published it as a plugin that can be directly referenced.

<script src="//cdn.jsdelivr.net/npm/@sy-records/docsify-footnotes/lib/index.min.js"></script>

jhildenbiddle commented 2 months ago

We are likely better served by allowing users to add marked extensions as needed.

docsifyjs / docsify