Properly render KaTeX formulas by replacing katex shortcode by katexinline and katexblock

[Azkellas]

Relevant issue: #633

katex shortcode includes KaTeX in the page but does not protect KaTeX formulas from being parsed by Hugo's markdown parser.
This PR fixes the problem by replacing it by two encasing shortcodes katexblock and katexinline.

The partial vendors checks if any of these two shortcodes is present in the page and if so, it includes the KaTeX lib. katex shortcode is removed from the shortcodes.

The two new shortcodes are used as follows:

Inline notation: {{< katexinline >}}\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…{{< /katexinline >}}

block notation:
{{< katexblock >}}
 \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
{{< /katexblock >}}

The names are a bit long (especially for inline), but more explicit is often better than shorter. I'm open to suggestions.

Note:

• as it stands, this is a breaking change. I don't know the policy on Congo on this, but I think this is needed since the current implementation is very easy to break and not really useful since most expressions won't be rendered properly and I can't see any ways to fix it while keeping the same syntax. It is possible to have both behaviors at the same time to ensure compatibility if needed.
• for the jp/es localization, I used DeepL, so it might not be perfect. My English is far from perfect too, so feel free to correct me.

[netlify]

✅ Deploy Preview for hugo-congo ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	9889294
🔍 Latest deploy log	https://app.netlify.com/sites/hugo-congo/deploys/651951f7ff9ded0008555952
😎 Deploy Preview	https://deploy-preview-634--hugo-congo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[jpanther]

Thanks for the PR, I wonder if there's a better way we can implement this so that it keeps the katex shortcode name the same so that it can fall back gracefully to a non-breaking behaviour? For instance, is it possible to detect in the shortcode whether it's inline or block? Otherwise perhaps it could be through a parameter, something like {{< katex mode="inline" >}}. Interested in your thoughts on if this is a better way forward?

[Azkellas]

I agree, it's better to avoid a breaking change.

It would make the shortcode even longer tough, which is not ideal especially for inline blocks.
Maybe making it a positional argument would be better for conciseness, like {{< katex inline >}} and {{< katex block >}}, which is close to what I had while both keeping the same name and being more readable. I've managed to implement it this way and I like it better.

We can also make inline the default mode, so that it is not necessary to specify it in lines.

We could also merge this shortcode with my proposal for katex macros support (see #637) with a {{< katex macros >}}. A single shortcode for all cases.

On the other hand, detecting in the shortcode means asking the user to specify whether it's a block or inline with $$ $$ and /( /) (the katex shortcode would just be a raw shortcode). I'm not fond of requiring both a shortcode and a type in two different syntaxes.

So my new proposal is:

• {{< katex >}} and {{< katex inline >}} render inlines
• {{< katex block >}} renders blocks
• ({{< katex macros >}} for macros if accepted)
• {{< katex invalid_parameter_name >}} throws an "Invalid katex mode" compile error

What do you think?

[Azkellas]

I revisited my macro implementation to follow the proposal above. Sadly this is still a broken change since these blocks require an .Inner and the current behaviour is to add an unclosed {{< katex >}} shortode.
Since hugo v.0.111.0 shortcodes that use .Inner need to be properly closed which means I can't repurpose the current katex shortcode without a breaking change. Users would have to replace {{< katex >}} with {{< katex />}} in their affected posts.

I'm not sure how you want to proceed with this.

[Azkellas]

in the meantime I updated the PR to mirror the proposal above and speed up the process.

[github-actions]

This pull request has been automatically marked as stale because it has not had any recent activity.
Please review the PR history and add a reply with any requested information. If no information has been requested, it may be that this contribution does not fit with the project objectives, or does not adhere to the contributing guidelines. If this is in error, please add a reply with further details.
This PR will automatically close in 30 days if no further activity occurs.