docsifyjs
Please support markdown footnotes [^1] [^note]
Feature request
What problem does this feature solve?
To cite the Markdown Guide:
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.
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
@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. :(
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?
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. 1
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: ');
}
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>
