equation in {{#include}} not rendered

[expikr]

Steps to reproduce:

src.md

## My equation
$$
E=mc^2
$$

ch1.md

# Chapter 1
{{#include src.md}}

SUMMARY.md

[original](./src.md)
[included](./ch1.md)

[SichangHe]

Any idea on how to solve this?

I have known this problem for a while. We had to work around it by not using #include.

[expikr]

My workaround:

src.md

## My equation
$$
E=mc^2
$$

ch1.md

{{#include katex.md}}
# Chapter 1
{{#include src.md}}

katex.md

  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body,{
          delimiters: [
            {left: "$$", right: "$$", display: true},
            {left: "$", right: "$", display: false},
            {left: "\\(", right: "\\)", display: false},
            {left: "\\[", right: "\\]", display: true}
          ]
        });
    });
  </script>

[SichangHe]

You are simply using KaTeX in browser instead of using a preprocessor for the math expression. In this workaround, mdbook-katex has no effect.

[expikr]

Perhaps you should just rip a snapshot of the KaTeX code used to render the equations and put it among the output files, then insert into every page an #include referencing the local snapshot? A clientside fallback for "catching" edgecases that didn't get serverside-rendered by the preprocessor. Make it an optional flag perhaps, just like the no-css selfhost.

Speaking of which, what's wrong with mdbook-katex just ripping the css automatically anyways when the no-css flag is set? I don't think there are any license restrictions preventing you from just distributing the js and css snapshot in the output?

[SichangHe]

Perhaps you should just rip a snapshot of the KaTeX code used to render the equations and put it among the output files, then insert into every page an #include referencing the local snapshot?

I don't think I understand what you are saying here. What is "a snapshot of the KaTeX code used to render the equations?"

A clientside fallback for "catching" edgecases that didn't get serverside-rendered by the preprocessor.

This is a horrible hack that the users might be okay with.

[SichangHe]

Speaking of which, what's wrong with mdbook-katex just ripping the css automatically anyways when the no-css flag is set?

What do you mean by "ripping the css?" Do you mean that we include the CSS in the binary and directly write it?

I don't think there are any license restrictions preventing you from just distributing the js and css snapshot in the output?

The problem about licenses would probably be on the fonts.

---

These should be for another issue.

[SichangHe]

I need to read the mdbook source code to see why #include is handled after external preprocessors. That would be the solution.

[SichangHe]

I found the solution:

[preprocessor.katex]
after = ["links"]

I will update the README.

[SichangHe]

@expikr, please validate whether this solution works.

[expikr]

works, thanks!

Are there any consideration against this being made the default value?

[SichangHe]

works, thanks!

Great!

Is there any consideration preventing this from being made the default?

This is controlled by mdBook's behavior. By default, mdBook runs external preprocessors such as katex before its internal preprocessors such as links which handles #include. The after option can be used to specify the order.

Does that answer your concern?

[expikr]

Oh, I meant being made the default value for that flag, like how the default value of block-delimiter is {left = "$$", right = "$$"}, it makes sense to just make mdbook-katex's own after default to ["links"]

[SichangHe]

Your proposal does not work to my knowledge, unfortunately. We can only have defaults if the option is for mdbook-katex, but in this case, the option is for mdBook.

Options are read by mdBook. mdBook then passes these options to preprocessors such as mdbook-katex, where mdbook-katex would read options such as block-delimiter, so we can have a default in mdbook-katex there.

after is an option handled by mdBook itself instead of mdbook-katex. mdBook uses after and before to decide the order it calls the preprocessors, which is beyond any preprocessors' control.

Is that clear?

[expikr]

I see, so the default values are simply what the preprocessor internally assumes if it did not receive any value from mdbook, rather than something that the preprocessor can declare to mdbook?

[SichangHe]

Yes. Preprocessors can, in fact, only output book (content) not cfg (configuration) to mdBook.

mdBook has rather poor documentation on these topics, sadly. I had to read the mdBook source code to make some parts in mdbook-katex functioning.