feature: add support for GLFM math blocks (#752)

* feat: add support for GLFM math blocks

This add supports for GLFM's math blocks [1] using hugo's Markdown
render hooks [2].

[1]: https://docs.gitlab.com/ee/user/markdown.html#math
[2]: https://gohugo.io/templates/render-hooks/#render-hooks-for-code-blocks

KaTeX is loaded automatically once a math code block is found on the page

* style: update KaTex output style

* chore: add a blank line at the end

* perf: reduce the duplicate code

* docs: improve math typesetting docs

Co-authored-by: razonyang <razonyang@gmail.com>

assets/katex/scss/index.scss

@@ -1,23 +1,5 @@
 @import 'katex/dist/katex';
 
-.katex-display > .katex {
-  display: inline-block;
-  white-space: nowrap;
-  max-width: 100%;
-  overflow-x: scroll;
-  text-align: initial;
-}
-
-.katex-display {
-  .katex {
-    max-width: 100%;
-
-    .katex-html {
-      max-width: 100%;
-      overflow-x: auto;
-      overflow-y: hidden;
-      padding-left: 2px;
-      padding-right: 2px;
-    }
-  }
+.math-output {
+  overflow: auto;
 }

exampleSite/content/posts/math-typesetting/index.md

@@ -3,7 +3,6 @@ author: Hugo Authors
 title: Math Typesetting
 date: 2019-03-08
 description: A brief guide to setup KaTeX
-math: true
 categories:
 tags:
   - Math
@@ -16,19 +15,26 @@ Mathematical notation in a Hugo project can be enabled by using third party Java
 
 This theme supports [KaTeX](https://katex.org/).
 
-- To enable KaTeX globally set the parameter `math` to `true` in a project's configuration
-- To enable KaTeX on a per page basis include the parameter `math: true` in content files
+- When using a `math` [code block](#math-code-block) or `katex` shortcode, KaTeX is activated automatically.
+- To manually enable KaTeX globally set the parameter `math` to `true` in a project's configuration file.
+- To enable KaTeX on a per page basis include the parameter `math: true` in the frontmatter of the content files.
 
 **Note:** Use the online reference of [Supported TeX Functions](https://katex.org/docs/supported.html)
 
 ## Examples
 
 ### Inline
 
-Such as \\(\KaTeX\\) and $\LaTeX$.
+Such as `\\(\KaTeX\\)`(\\(\KaTeX\\)) and `$\LaTeX$`($\LaTeX$).
 
 ### Block
 
+```markdown
+$$
+FORMULA
+$$
+```
+
 $$
   \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
 $$
@@ -37,7 +43,29 @@ $$
   \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } 
 \\]
 
-### Multiple lines
+### Math code block(recommended)
+
+See [GitLab Flavored Markdown](https://docs.gitlab.com/ee/user/markdown.html#math).
+
+````markdown
+```math
+FORMULA
+```
+````
+
+The probability of getting \\(k\\) heads when flipping \\(n\\) coins is:
+
+```math
+\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
+```
+
+### Multiple lines via shortcode(recommended)
+
+```markdown
+{{</* katex */>}}
+FORMULA
+{{</* /katex */>}}
+```
 
 {{< katex >}}
   \begin{array}{l}

layouts/_default/_markup/render-codeblock-math.html

@@ -0,0 +1,4 @@
+{{ .Page.Store.Set "hasKaTeX" true -}}
+<div class="math-output">$$
+{{ .Inner | safeHTML }}
+$$</div>

layouts/partials/assets/math/css.html

@@ -1,3 +1,3 @@
-{{- if or .Params.math .Site.Params.math }}
+{{- if (partial "assets/math/enable" .) }}
   {{- partial "assets/katex/css" . }}
 {{- end -}}

layouts/partials/assets/math/enable.html

@@ -0,0 +1,7 @@
+{{- return
+    or
+    .Params.math
+    .Site.Params.math
+    (.HasShortcode "katex")
+    (.Page.Store.Get "hasKaTeX")
+}}

layouts/partials/assets/math/js.html

@@ -1,3 +1,3 @@
-{{- if or .Params.math .Site.Params.math -}}
-{{ partial "assets/katex/js" . }}
+{{- if (partial "assets/math/enable" .) }}
+  {{ partial "assets/katex/js" . }}
 {{- end -}}

layouts/shortcodes/katex.html

@@ -1,3 +1,5 @@
+<div class="math-output">
 $$
   {{ .Inner }}
-$$
+$$
+</div>