Server-side Markdown Footnote Inline rendering

[paulcrown]

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.

[ssddanbrown]

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

[paulcrown]

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.

[ssddanbrown]

@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.

[paulcrown]

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]

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.

[DanielGordonIT]

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.