diff --git a/README.md b/README.md index 441948295..22d2eb1fa 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ to see what's still missing. - [Extensible to make it suit your needs](#extensibility) - Responsive, mobile-first design - Beautiful SVG icons with [Tabler Icons](https://tabler-icons.io/) +- [Math typesetting](#math-typesetting) via Hugo's [embedded KaTeX engine](https://gohugo.io/functions/transform/tomath/) A big thank you to the authors of the software that make this theme possible! ❤️ @@ -414,97 +415,53 @@ The easiest way to replace the default favicons is to generate them using RealFaviconGenerator.net and put the generated files into the `static/` directory. -## Extensibility - -You can extend the theme by overriding the following partials in the -`layouts/partials` directory which by default are empty placeholder files: - -- [`head/head_start.html`](./layouts/partials/head_start.html) - Custom HTML at the start of `` -- [`head/head_end.html`](./layouts/partials/head_end.html) - Custom HTML at the end of `` -- [`footer_end.html`](./layouts/partials/footer_end.html) - Custom HTML at the end of `` -- [`comments.html`](./layouts/partials/comments.html) - Comments at the end of posts +## Math Typesetting -### Example: Adding KaTeX Support to the Theme +For math typesetting in a Hugo project, you can leverage hugo's internal +[KaTeX](https://katex.org/) rendering engine. -[KaTeX](https://katex.org/) is a fast, easy-to-use JavaScript library for TeX -math rendering on the web. Let's add it to the theme via `npm`. First, add the -following to the `package.hugo.json` file: +If you want to use mathematical or chemical equations in site, enable the +[Goldmark passthrough extension](https://gohugo.io/render-hooks/passthrough/) +and define delimiters for block and inline formulae in your config file: -```json -"dependencies": { - "katex": "^0.16.8" -} -``` - -Then run `hugo mod npm pack` to sync the `package.hugo.json` dependencies with -`package.json`. Run `npm install` after. We then need to mount the -`node_modules/katex` folder into Hugo's virtual filesystem by adding the -following to the `config/_default/module.toml` file: +**`hugo.toml`** ```toml -[[mounts]] - source = "node_modules/katex" - target = "assets/katex" +[markup] + [markup.goldmark] + [markup.goldmark.extensions] + [markup.goldmark.extensions.passthrough] + enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] ``` -We can then add the following to `layouts/partials/head/head_end.html`: +Afterwards you can author formulae using the standard $\LaTeX$ syntax: - +### Examples -```html -{{ if .Params.katex }} - {{ $katexCSS := resources.Get "katex/dist/katex.min.css" }} - - - {{ $katexJS := resources.Get "katex/dist/katex.min.js" }} - - - {{ $autoRender := resources.Get "katex/dist/contrib/auto-render.min.js" }} - -{{ end }} -``` +Inline math: $\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887… $ - +Block math: -The only thing left is enabling KaTeX in the front matter of our content: +$$ +\tag*{(1)} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } +$$ -```markdown ---- -title: "Hello World" -description: "The first post of this blog" -date: 2021-03-14T15:00:21+01:00 -draft: false -katex: true ---- +## Extensibility -I'm a .NET developer by trade, so let's say hello in C#! -``` +You can extend the theme by overriding the following partials in the +`layouts/partials` directory which by default are empty placeholder files: + +- [`head/head_start.html`](./layouts/partials/head_start.html) + Custom HTML at the start of `` +- [`head/head_end.html`](./layouts/partials/head_end.html) + Custom HTML at the end of `` +- [`footer_end.html`](./layouts/partials/footer_end.html) + Custom HTML at the end of `` +- [`comments.html`](./layouts/partials/comments.html) + Comments at the end of posts ## Configure the Tag Cloud diff --git a/config/_default/hugo.toml b/config/_default/hugo.toml index 138bb24f3..2f5266b4c 100644 --- a/config/_default/hugo.toml +++ b/config/_default/hugo.toml @@ -1,11 +1,13 @@ baseURL = "http://localhost" copyright = "Copyright © 2021" title = "hugo-theme-gruvbox" -#paginate = 10 enableRobotsTXT = true # Enable to calculate the last modified date from Git history and show it in the post header #enableGitInfo = true +[pagination] + #pagerSize = 10 + [build] noJSConfigInAssets = true [build.buildStats] @@ -17,6 +19,12 @@ enableRobotsTXT = true [markup] [markup.goldmark] + [markup.goldmark.extensions] + [markup.goldmark.extensions.passthrough] + enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] [markup.goldmark.renderer] # This setting allows inlining - -{{ end }} -{{}} +Afterwards you can author formulae using the standard \(\LaTeX\) syntax: ### Examples -{{< math.inline >}} -

-Inline math: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\) -

-{{}} +Inline math: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887… \) Block math: + $$ - \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } +\tag*{(1)} \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$ + +Chemical equations: + +\[ +\tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}$} +\] + +**Note:** Use the online reference of [Supported TeX Functions](https://katex.org/docs/supported.html) diff --git a/layouts/_default/_markup/render-passthrough.html b/layouts/_default/_markup/render-passthrough.html new file mode 100644 index 000000000..0ed001133 --- /dev/null +++ b/layouts/_default/_markup/render-passthrough.html @@ -0,0 +1,9 @@ +{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} +{{- with try (transform.ToMath .Inner $opts) }} + {{- with .Err }} + {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} + {{- else }} + {{- .Value }} + {{- $.Page.Store.Set "hasMath" true }} + {{- end }} +{{- end -}} diff --git a/layouts/partials/head/head.html b/layouts/partials/head/head.html index a7582dfd2..e539dd1a7 100644 --- a/layouts/partials/head/head.html +++ b/layouts/partials/head/head.html @@ -15,6 +15,20 @@ {{ partial "head/favicons.html" . }} + {{ $noop := .WordCount }} + {{ if .Page.Store.Get "hasMath" }} + {{ $katex_css_url := printf "https://cdn.jsdelivr.net/npm/katex@latest/dist/katex%s.css" (cond hugo.IsProduction ".min" "") -}} + {{ with try (resources.GetRemote $katex_css_url) -}} + {{ with .Err -}} + {{ errorf "Could not retrieve KaTeX css file from CDN. Reason: %s." . -}} + {{ else with.Value -}} + {{ with resources.Copy (printf "css/katex%s.css" (cond hugo.IsProduction ".min" "")) . }} + {{ $secureCSS := . | resources.Fingerprint "sha512" -}} + + {{ end -}} + {{ end -}} + {{ end -}} + {{ end }} {{ partial "head/head_end.html" . }}