markdown-it Footnote support #1370

New Issue

OVERLORD · 2026-02-05T00:43:04+03:00

OVERLORD commented

2026-02-05 00:43:04 +03:00

Originally created by @Epsola on GitHub (Sep 18, 2019).

Describe the feature you'd like
Support for Markdown footnotes through the markdown-it-footnotes.

Describe the benefits this feature would bring to BookStack users
Technical text books, documentation and many other types of books make use of footnotes. This will allow writers to easily add footnotes either inline or linked through the book text using Markdown.

Originally created by @Epsola on GitHub (Sep 18, 2019). **Describe the feature you'd like** Support for Markdown footnotes through the [markdown-it-footnotes](https://github.com/markdown-it/markdown-it-footnote). **Describe the benefits this feature would bring to BookStack users** Technical text books, documentation and many other types of books make use of footnotes. This will allow writers to easily add footnotes either inline or linked through the book text using Markdown.

OVERLORD added the > Markdown Editor 💻 Front-End labels 2026-02-05 00:43:04 +03:00

OVERLORD closed this issue

2026-02-05 00:43:07 +03:00

OVERLORD commented

2026-02-05 00:43:09 +03:00

@berot3 commented on GitHub (Jan 22, 2020):

I hope it's not too hard ti implement since bookstack is using markdown-it already?

This is also one feature that is stopping me from switching over to bookstackapp :(

@berot3 commented on GitHub (Jan 22, 2020): I hope it's not too hard ti implement since bookstack is using markdown-it already? This is also one feature that is stopping me from switching over to bookstackapp :(

OVERLORD commented

2026-02-05 00:43:13 +03:00

@ssddanbrown commented on GitHub (Apr 1, 2020):

Within BookStack I generally stick to the commonmark spec fairly strictly to provide standardisation and a set scope of supported syntax. Footnote functionality or syntax is not part of the spec hence is not something I'd support as part of the core project.

That said, I did recently add some custom-emitted events so people could easily hook in to some core front-end libraries. Here's an example of using this to add footnote support:

<script src="https://cdnjs.cloudflare.com/ajax/libs/markdown-it-footnote/3.0.2/markdown-it-footnote.min.js"></script>
<script>
	window.addEventListener('editor-markdown::setup', function(event) {
		const mdIt = event.detail.markdownIt;
		mdIt.use(window.markdownitFootnote)
	});
</script>

You should be able to copy+paste that into the "Custom HTML Head Content" setting and it will make footnotes work in the markdown editor in the current version of BookStack.

Note, this functionality does remain technically out-of-support so things could change in the future. If it does then feel free to still raise a breakage here, and i'll see if we can open up a "hook" at least for a workaround, as we have done here.

Otherwise, since this falls out of the targeted commonmark spec to be officially included, I'll close this off as out-of-scope.

@ssddanbrown commented on GitHub (Apr 1, 2020): Within BookStack I generally stick to the commonmark spec fairly strictly to provide standardisation and a set scope of supported syntax. Footnote functionality or syntax is not part of the spec hence is not something I'd support as part of the core project. That said, I did recently add some custom-emitted events so people could easily hook in to some core front-end libraries. Here's an example of using this to add footnote support: ```html <script src="https://cdnjs.cloudflare.com/ajax/libs/markdown-it-footnote/3.0.2/markdown-it-footnote.min.js"></script> <script> window.addEventListener('editor-markdown::setup', function(event) { const mdIt = event.detail.markdownIt; mdIt.use(window.markdownitFootnote) }); </script> ``` You should be able to copy+paste that into the "Custom HTML Head Content" setting and it will make footnotes work in the markdown editor in the current version of BookStack. Note, this functionality does remain technically out-of-support so things could change in the future. If it does then feel free to still raise a breakage here, and i'll see if we can open up a "hook" at least for a workaround, as we have done here. Otherwise, since this falls out of the targeted commonmark spec to be officially included, I'll close this off as out-of-scope.

OVERLORD commented

2026-02-05 00:43:15 +03:00

@AlphaJack commented on GitHub (Feb 14, 2021):

@ssddanbrown Any hint on why it is correctly rendered in the editor preview (center), but not in the final page (right)?

The final page HTML contains the js snippet, and neither the console or the network tab report any error.

@AlphaJack commented on GitHub (Feb 14, 2021): @ssddanbrown Any hint on why it is correctly rendered in the editor preview (center), but not in the final page (right)? ![Screenshot_20210214_140838](https://user-images.githubusercontent.com/19962243/107877726-07e59b00-6ec6-11eb-80d6-0493d39cd551.png) The final page HTML contains the js snippet, and neither the console or the network tab report any error.

OVERLORD commented

2026-02-05 00:43:18 +03:00

@ssddanbrown commented on GitHub (Feb 16, 2021):

@AlphaJack As of v0.31, final Markdown for the page is rendered server-side instead.

The library we use on the backend does have a footnotes extension, but we might need to expose some hooks for people to customize the back-end abilities.

Feel free to open a new issue requesting back-end markdown customization.

@ssddanbrown commented on GitHub (Feb 16, 2021): @AlphaJack As of v0.31, final Markdown for the page is rendered server-side instead. The library we use on the backend does have a [footnotes extension](https://commonmark.thephpleague.com/1.5/extensions/footnotes/), but we might need to expose some hooks for people to customize the back-end abilities. Feel free to open a new issue requesting back-end markdown customization.

OVERLORD commented

2026-02-05 00:43:22 +03:00

@AlphaJack commented on GitHub (Feb 16, 2021):

So, now footnotes should work out of the box, right?
Server-side rendering means no more support for client-side rendering with Mermaid and KaTeX? Does it happen when saving a page or each time a client requests it?

@AlphaJack commented on GitHub (Feb 16, 2021): So, now footnotes should work out of the box, right? Server-side rendering means no more support for client-side rendering with Mermaid and KaTeX? Does it happen when saving a page or each time a client requests it?

OVERLORD commented

2026-02-05 00:43:28 +03:00

@ssddanbrown commented on GitHub (Feb 18, 2021):

@AlphaJack

So, now footnotes should work out of the box, right?

No, We only support commonmark elements + tables + tasklists within the BookStack core.

Server-side rendering means no more support for client-side rendering with Mermaid and KaTeX? Does it happen when saving a page or each time a client requests it?

If this was added via front-end JavaScript, and did not alter the HTML before being sent to the server, there should be no change. In my original statement, I just mean that markdown to HTML conversion for page content is now done back-end as of v0.31.

@ssddanbrown commented on GitHub (Feb 18, 2021): @AlphaJack > So, now footnotes should work out of the box, right? No, We only support commonmark elements + tables + tasklists within the BookStack core. > Server-side rendering means no more support for client-side rendering with Mermaid and KaTeX? Does it happen when saving a page or each time a client requests it? If this was added via front-end JavaScript, and did not alter the HTML before being sent to the server, there should be no change. In my original statement, I just mean that markdown to HTML conversion for page content is now done back-end as of v0.31.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#1370