Add math typesetting support with KaTex

frjo / hugo-theme-zen

A fast and clean Hugo base theme with css-grid and Hugo pipes support.

https://zen-demo.xdeb.org/

GNU General Public License v2.0

264 stars 75 forks source link

Add math typesetting support with KaTex #80

Closed Celqaz closed 1 year ago

Celqaz commented 1 year ago

Fix #29

Thanks for your dedication to such a great theme.

I figure out a way to add math support in Zen, using KaTex(v0.16.4).

Users now can turn on math typesetting in two ways:

Applied globally

In config.yaml:
```
params:
...
 math: true
```
Applied in one single post

In config.yaml:
```
params:
...
 math: false
```
And in one post's front matter:
```
math: true
```

Celqaz commented 1 year ago

Thanks for your constructive comments and detailed guidance; I will address them subsequently.

Celqaz commented 1 year ago

All the newly mentioned changes have been made; please review. : )

frjo commented 1 year ago

Thanks for your contribution!

Celqaz commented 1 year ago

Thanks for your contribution!

Thanks for your patient guidance and detailed feedback; I have learnt far more from this than I have ever given.

frjo commented 1 year ago

@Celqaz I have changed the Katex support in the Zen theme a bit after testing it. Please try it out and let my know how it works for you.

From the updated README:

Download the latest release from https://github.com/KaTeX/KaTeX/releases. Unpack and place the resulting "katex" directory in the root static directory.

The resulting path should be static/katex. Then set the math param to "true" and write some math to be typeset.

Katex needs fonts etc., all in all it is 3 MB of files. I thought it better that people who needs this downloads the files. This way they get the latest version and everyone else do not have 3 MB of unused files.

I'm interested to know what settings is a good default for the autorenderer. I found out the following was needed to support both inline and block rendering.

https://github.com/frjo/hugo-theme-zen/blob/eee22b08f59c7d7ee008dd58c8a2c167ab8ed3df/assets/js/math.js#L10-L19

Celqaz commented 1 year ago

It worked perfectly for me. 🎉

To avoid the font files increasing the size of this theme, I previously changed the fonts' relative address in the official katex.min.css file to the absolute address of the CDN.

But the current version lets users download what they need, which is a more elegant way to solve such issues, especially taking those who don't need math typesetting into account; great work ; )