Server-side Markdown Footnote Inline rendering #2181

New Issue

OVERLORD · 2026-02-05T03:13:02+03:00

OVERLORD commented

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

Originally created by @paulcrown on GitHub (Apr 3, 2021).

I see as of v0.31, final Markdown for the page is rendered server-side, and the library used on the backend does have a footnotes extension, but I don't have the expertise to understand how to utilize this in BookStack.

@ssddanbrown in https://github.com/BookStackApp/BookStack/issues/1671#issuecomment-779447882_ indicated that a back-end markdown customization could be requested.

Because I had been using 'Custom HTML Head Content' to include markdown-it-footnote.min.js, all of my page Previews still render footnotes perfectly. However, all pages while not editing/Preview, simply display markdown notations in the text.

I am currently using BookStack v0.31.8.

I am requesting back-end markdown customization to allow inline footnotes, or alternatively, enlightenment as to how I should go about such myself.

Thank you.

Originally created by @paulcrown on GitHub (Apr 3, 2021). I see as of v0.31, final Markdown for the page is rendered server-side, and the library used on the backend does have a [footnotes extension](https://commonmark.thephpleague.com/1.5/extensions/footnotes/), but I don't have the expertise to understand how to utilize this in BookStack. @ssddanbrown in https://github.com/BookStackApp/BookStack/issues/1671#issuecomment-779447882_ indicated that a back-end markdown customization could be requested. Because I had been using 'Custom HTML Head Content' to include markdown-it-footnote.min.js, all of my page Previews still render footnotes perfectly. However, all pages while not editing/Preview, simply display markdown notations in the text. I am currently using BookStack v0.31.8. I am requesting back-end markdown customization to allow inline footnotes, or alternatively, enlightenment as to how I should go about such myself. Thank you.

OVERLORD added the 🏭 Back-End label 2026-02-05 03:13:02 +03:00

OVERLORD closed this issue

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

OVERLORD commented

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

@ssddanbrown commented on GitHub (Apr 6, 2021):

Hi @paulcrown,
This has actually now been implemented as part of #2639, But just awaiting release (Finishing up the docs/post now but may take a while).

We'll keep this open and I'll try to remember to post back here after release with an example and to get feedback on the implementation.

FYI @AlphaJack

@ssddanbrown commented on GitHub (Apr 6, 2021): Hi @paulcrown, This has actually now been implemented as part of #2639, But just awaiting release (Finishing up the docs/post now but may take a while). We'll keep this open and I'll try to remember to post back here after release with an example and to get feedback on the implementation. FYI @AlphaJack

OVERLORD commented

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

@paulcrown commented on GitHub (Apr 6, 2021):

Hi @paulcrown,
This has actually now been implemented as part of #2639, But just awaiting release (Finishing up the docs/post now but may take a while).

@ssddanbrown Thanks, I look forward to its release.

@paulcrown commented on GitHub (Apr 6, 2021): > Hi @paulcrown, > This has actually now been implemented as part of #2639, But just awaiting release (Finishing up the docs/post now but may take a while). @ssddanbrown Thanks, I look forward to its release.

OVERLORD commented

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

@ssddanbrown commented on GitHub (Apr 13, 2021):

@paulcrown @AlphaJack 21.04 is now out: https://www.bookstackapp.com/blog/bookstack-release-v21-04/

Tweaking the markdown rendering server-side is done via the logical theme system. Follow the getting started up the instructions to get setup with a functions.php file: https://github.com/BookStackApp/BookStack/blob/release/dev/docs/logical-theme-system.md. Note, this system is still in early stages to subject to change.

Heres the functions.php file code that gets footnote rendering working on my instance:

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use League\CommonMark\ConfigurableEnvironmentInterface;
use League\CommonMark\Extension\Footnote\FootnoteExtension;

Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(ConfigurableEnvironmentInterface $environment) {
    $environment->addExtension(new FootnoteExtension());
});

I've not tested with the other front-end library footnotes so there may be differences in rendering or parsing compared to the preview but let me know how that goes.

@ssddanbrown commented on GitHub (Apr 13, 2021): @paulcrown @AlphaJack 21.04 is now out: https://www.bookstackapp.com/blog/bookstack-release-v21-04/ Tweaking the markdown rendering server-side is done via the logical theme system. Follow the getting started up the instructions to get setup with a `functions.php` file: https://github.com/BookStackApp/BookStack/blob/release/dev/docs/logical-theme-system.md. Note, this system is still in early stages to subject to change. Heres the `functions.php` file code that gets footnote rendering working on my instance: ```php <?php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; use League\CommonMark\ConfigurableEnvironmentInterface; use League\CommonMark\Extension\Footnote\FootnoteExtension; Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(ConfigurableEnvironmentInterface $environment) { $environment->addExtension(new FootnoteExtension()); }); ``` I've not tested with the other front-end library footnotes so there may be differences in rendering or parsing compared to the preview but let me know how that goes.

OVERLORD commented

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

@paulcrown commented on GitHub (Apr 14, 2021):

21.04 is now out: https://www.bookstackapp.com/blog/bookstack-release-v21-04/

Tweaking the markdown rendering server-side is done via the logical theme system. Follow the getting started up the instructions to get setup with a functions.php file: https://github.com/BookStackApp/BookStack/blob/release/dev/docs/logical-theme-system.md. Note, this system is still in early stages to subject to change.

@ssddanbrown Thanks for all your work. I did see the release come out this week. I have updated my instance, and added a themes/footnote/functions.php with the code as you suggest. However, I was unable to get Inline rendering of footnotes to work, except in preview.

If I leave the Custom HTML Header blank, the preview screen shows no footnotes:

The page view is without a footnote:

Here is the page source to show no header:

If I instead, include a Custom HTML Header, then the preview is correct:

But the page view, loses the footnote again. This is the same as @AlphaJack was experiencing.

Here I show the page source with the Custom HTML Header included:

I copied your latest version of function.php into theme/footnote/functions.php, but I don't see that anything has changed. Any suggestions for me, as to where to look or test next?

@paulcrown commented on GitHub (Apr 14, 2021): > 21.04 is now out: https://www.bookstackapp.com/blog/bookstack-release-v21-04/ > > Tweaking the markdown rendering server-side is done via the logical theme system. Follow the getting started up the instructions to get setup with a `functions.php` file: https://github.com/BookStackApp/BookStack/blob/release/dev/docs/logical-theme-system.md. Note, this system is still in early stages to subject to change. @ssddanbrown Thanks for all your work. I did see the release come out this week. I have updated my instance, and added a themes/footnote/functions.php with the code as you suggest. However, I was unable to get Inline rendering of footnotes to work, except in preview. If I leave the Custom HTML Header blank, the preview screen shows no footnotes: ![Screenshot_2021-04-10 Editing Page Custom Header Blank](https://user-images.githubusercontent.com/8922235/114620294-0e4b8580-9c71-11eb-9ae9-c63a8a60c631.png) The page view is without a footnote: ![Screenshot_2021-04-10 Custom HTML Header Blank](https://user-images.githubusercontent.com/8922235/114620291-0db2ef00-9c71-11eb-8d95-22799510ab59.png) Here is the page source to show no header: ![Screenshot_2021-04-10 Source Custom HTML Header Blank](https://user-images.githubusercontent.com/8922235/114620297-0e4b8580-9c71-11eb-84fe-02d445f77e00.png) If I instead, include a Custom HTML Header, then the preview is correct: ![Screenshot_2021-04-11 Editing Page Custom HTML Header MD-i-f](https://user-images.githubusercontent.com/8922235/114620303-0ee41c00-9c71-11eb-87f5-11f2a398bfeb.png) But the page view, loses the footnote again. This is the same as @AlphaJack was experiencing. ![Screenshot_2021-04-11 Custom HTML Header MD-i-f](https://user-images.githubusercontent.com/8922235/114620301-0ee41c00-9c71-11eb-8224-5fc3a6e92228.png) Here I show the page source with the Custom HTML Header included: ![Screenshot_2021-04-11 Source HTML Header MD-i-f](https://user-images.githubusercontent.com/8922235/114620304-0ee41c00-9c71-11eb-9c40-997cf530c1c1.png) I copied your latest version of function.php into theme/footnote/functions.php, but I don't see that anything has changed. Any suggestions for me, as to where to look or test next?

OVERLORD commented

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

@paulcrown commented on GitHub (Apr 26, 2021):

I confirmed the functions.php file was in the theme/footnotes/ directory, and that APP_THEME="footnotes" to match the name of the theme directory.

While inline footnotes were still only working in preview mode, I have discovered that if I edit, make any change, and save each page that has inline footnotes, they work now.

@ssddanbrown My problem is solved with the new theme hook, provided I make at least one edit to each page.

@paulcrown commented on GitHub (Apr 26, 2021): I confirmed the functions.php file was in the theme/footnotes/ directory, and that APP_THEME="footnotes" to match the name of the theme directory. While inline footnotes were still only working in preview mode, I have discovered that if I edit, make any change, and save each page that has inline footnotes, they work now. @ssddanbrown My problem is solved with the new theme hook, provided I make at least one edit to each page.

OVERLORD commented

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

@DanielGordonIT commented on GitHub (Jan 23, 2024):

Heres the functions.php file code that gets footnote rendering working on my instance:
<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use League\CommonMark\ConfigurableEnvironmentInterface;
use League\CommonMark\Extension\Footnote\FootnoteExtension;

Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(ConfigurableEnvironmentInterface $environment) {
    $environment->addExtension(new FootnoteExtension());
});
I've not tested with the other front-end library footnotes so there may be differences in rendering or parsing compared to the preview but let me know how that goes.

Testing this, I found that it no longer takes a ConfigurableEnvironmentInterface but instead just an Environment. The code to include in the functions.php should now read:

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\Footnote\FootnoteExtension;

Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(Environment $environment) {
    $environment->addExtension(new FootnoteExtension());
});

Putting this here for anyone like me who found the old version of the code and realized that it didn't work.

I don't have a good way of enabling interoperability between the WYSIWYG and markdown editors for this, but I don't think it'll be too important for my use case.

@DanielGordonIT commented on GitHub (Jan 23, 2024): > Heres the `functions.php` file code that gets footnote rendering working on my instance: > > ```php > <?php > > use BookStack\Facades\Theme; > use BookStack\Theming\ThemeEvents; > use League\CommonMark\ConfigurableEnvironmentInterface; > use League\CommonMark\Extension\Footnote\FootnoteExtension; > > Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(ConfigurableEnvironmentInterface $environment) { > $environment->addExtension(new FootnoteExtension()); > }); > ``` > > I've not tested with the other front-end library footnotes so there may be differences in rendering or parsing compared to the preview but let me know how that goes. Testing this, I found that it no longer takes a `ConfigurableEnvironmentInterface` but instead just an `Environment`. The code to include in the `functions.php` should now read: ```php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; use League\CommonMark\Environment\Environment; use League\CommonMark\Extension\Footnote\FootnoteExtension; Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(Environment $environment) { $environment->addExtension(new FootnoteExtension()); }); ``` Putting this here for anyone like me who found the old version of the code and realized that it didn't work. I don't have a good way of enabling interoperability between the WYSIWYG and markdown editors for this, but I don't think it'll be too important for my use case.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#2181