Merge pull request joshed-io#138 from deining/math-code-blocks

Support for math code blocks (incl. auto activation of MathJax)

README.md

@@ -322,38 +322,46 @@ Markdown surrounded by the markdown shortcode will not be rendered by Hugo but b
 {{% /markdown %}}
 ```
 
-### MathJax support
+### Maths and equations (via `MathJax`)
 
-Add the following to `layouts/partials/reveal-hugo/body.html`:
+### Option 1: `math` code block
 
+You can author your equation inside a `math` [code block](https://reveal-hugo.dzello.com/#/math-equations):
+
+````markdown
+```math
+\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
 ```
-<script>
-MathJax = {
-  tex: {
-    inlineMath: [['$', '$'], ['\\(', '\\)']]
-  },
-  svg: {
-    fontCache: 'global'
-  }
-};
-</script>
+````
+
+Use of the code block will automatically activate needed `MathJax` script for equation display.
 
-<script type="text/javascript" id="MathJax-script" async
-  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
-</script>
+If you want to use inline equations (like $E=mc^2$) wrap your math content in two single-\$:
+
+```markdown
+Albert Einstein's famous formula: $E=mc^2$
 ```
 
-Then you can do this in a slide:
+If you want to use inline equations and no `math` code block for auto activation is present in your slides, you need to manually enable `MathJax` by setting the parameter `math` to `true` in your page frontmatter.
 
+### Option 2: `math` shortcode
+
+Alternatively, you can author your equation inside a `math` [shortcode](https://reveal-hugo.dzello.com/#/math-shortcode):
+
+```markdown
+{{< math >}}
+\tag*{(1)} \frac{n!}{k!(n-k)!} = \binom{n}{k}
+{{< /math >}}
 ```
-## Cool equations
 
-Displayed equations are wrapped in double-\$
+Use of the shortcode will automatically activate needed `MathJax` script for equation display.
 
-$$\frac{n!}{k!(n-k)!} = \binom{n}{k}$$
+For inline equations (like $E=mc^2$) use the self closing form of the `math` shortcode:
 
-Inline equations like $E=mc^2$ are wrapped in single-\$
+```markdown
+Albert Einstein's famous formula: {{< math "E=mc^2" />}}
 ```
+For the sake of brevity, the inline content can be given as unnamed first shortcode parameter, as in the code fragment above. In a more concise form, the math content can also be assigned to a named shortcode parameter `inline`: `{{< math inline="E=mc^2" />}}`.
 
 ### HTML slides
 

exampleSite/content/home/configuration.md

@@ -1,6 +1,7 @@
 +++
 weight = 21
 +++
+{{< slide id=configuration >}}
 
 # Configuration
 

exampleSite/content/home/features.md

@@ -1,6 +1,7 @@
 +++
 weight = 10
 +++
+{{< slide id=included >}}
 
 ## What's included?
 
@@ -14,12 +15,14 @@ weight = 10
 [see the code on github](https://github.com/dzello/reveal-hugo)
 
 ---
+{{< slide id=features >}}
 
 ## Features
 
 - Write slides in Markdown in one or more files
 - Shortcodes for fragments, sections, slides & more
 - All Reveal.js parameters can be customized
 - Any Hugo section can be output as a presentation
-- Supports mermaid codeblocks
+- Supports math code blocks
+- Supports mermaid code blocks
 - Supports offline development or using a CDN

exampleSite/content/home/shortcodes/math.md

@@ -0,0 +1,34 @@
++++
+weight = 31
++++
+
+{{< slide id=math-shortcode >}}
+
+### Mathematical equations
+
+Use the `math` shortcode if you need to enable reveal-js highlighting module
+(`codeFences = false`).
+
+```code
+{{</* math */>}}
+\tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0
+{{</* /math */>}}
+```
+<small>
+displays as:
+</small>
+
+{{< math >}}
+\tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0
+{{< /math >}}
+
+For inline equations, use a self closed `math` shortcode:
+
+```code
+Albert Einstein's famous formula: {{</* math "E=mc^2" /*/>}}
+```
+<small>
+is rendered to:
+</small>
+
+Albert Einstein's famous formula: {{< math "E=mc^2" />}}

exampleSite/content/home/usage.md

@@ -1,10 +1,12 @@
 +++
 weight = 20
 +++
+{{< slide id=usage >}}
 
 # Usage
 
 ---
+{{< slide id=prerequisite >}}
 
 ## Prerequisite
 
@@ -34,6 +36,7 @@ Hello world!
 ```
 
 ---
+{{< slide id=adding-slides >}}
 
 ### Add slides
 
@@ -52,6 +55,37 @@ Hello program!
 ```
 
 ---
+{{< slide id=math-equations >}}
+
+### Cool equations
+
+For equations, you can use a [`math`](https://docs.gitlab.com/ee/user/markdown.html#math) code block:
+
+````code
+```math
+\tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0
+```
+````
+<small>
+renders to:
+</small>
+
+{{< math >}}
+\tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0
+{{< /math >}}
+
+Inline equations (e. g. $E=mc^2$) are wrapped in single $:
+
+```code
+Albert Einstein's famous formula: $E=mc^2$
+```
+
+<small>💡 Note: When using inline math only (no math code block present), you have to set `math=true` in the frontmatter of your slide page.</small>
+
+<small>💡 Note: for code blocks support (` ```math ...``` `), hugo highlighting must be on (`codeFences = true` in `config.toml`). If you want to set `codeFences = false`, use the `math` [shortcode](#/math-shortcode).</small>
+
+---
+{{< slide id=mermaid-diagrams >}}
 
 ### Mermaid
 
@@ -83,7 +117,7 @@ graph LR
     B --> C
 {{< /mermaid >}}
 
-<small>💡 Note: for codeblocks support (` ```mermaid ...``` `), hugo highlighting must be on (codeFences = true in config.toml)</small>
+<small>💡 Note: for code blocks support (` ```mermaid ...``` `), hugo highlighting must be on (codeFences = true in config.toml)</small>
 
 
 ---

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

@@ -0,0 +1,2 @@
+<p>$${{- .Inner | safeHTML }}$$</p>
+{{ .Page.Store.Set "hasMath" true -}}

layouts/partials/layout/javascript.html

@@ -57,10 +57,14 @@
       manage hot-reload by using the reveal ready event.
 */}}
 {{ $hasMermaid := false }}
+{{ $hasMath := false }}
 {{ range .Site.AllPages }}
   {{ if .Store.Get "hasMermaid" }}
     {{ $hasMermaid = true }}
   {{ end }}
+  {{ if or .Params.math (.Store.Get "hasMath")  }}
+    {{ $hasMath = true }}
+  {{ end }}
 {{ end }}
 
 {{ if $hasMermaid }}
@@ -89,6 +93,22 @@
   </script>
 {{ end }}
 
+{{ if $hasMath }}
+<script>
+  MathJax = {
+    tex: {
+      inlineMath: [['$', '$'], ['\\(', '\\)']]
+    },
+    svg: {
+      fontCache: 'global'
+    }
+  };
+</script>
+
+{{ $mathjaxSrc := resources.GetRemote "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js" }}
+<script type="text/javascript" id="MathJax-script" async src="{{ $mathjaxSrc.RelPermalink }}"></script>
+{{ end }}
+
 {{- $custom_js := $.Param "reveal_hugo.custom_js" -}}
 {{- if $custom_js -}}
 <script type="text/javascript" src="{{ $custom_js | relURL }}"></script>

layouts/shortcodes/math.html

@@ -0,0 +1,31 @@
+{{ $math := "" -}}
+
+{{ with .Get "inline" -}}
+  {{/* Error checking */ -}}
+  {{ if $.Inner -}}
+    {{ errorf "%s: shortcode math with parameter 'inline' must not have inner content declared" $.Page.File.Path -}}
+  {{ end -}}
+  {{ if ne ( printf "%T" . ) "string" -}}
+    {{ errorf "%s: shortcode math: parameter 'inline' must be a string" $.Page.File.Path -}}
+  {{ end -}}
+  {{ $math = . -}}
+{{ else -}}
+  {{ with $.Get 0 -}}
+    {{ if $.Inner -}}
+      {{ errorf "%s: shortcode math for inline content must not have inner content declared" $.Page.File.Path -}}
+    {{ end -}}
+    {{ $math = $.Get 0 -}}
+  {{ else }}
+  {{ if .IsNamedParams}}  
+      {{ errorf "%s: shortcode math: Invalid named parameter(s) (%v) detected. Only named parameter 'inline' is allowed." $.Page.File.Path .Params -}}
+    {{ end }}
+  {{ end -}}
+{{ end -}}
+
+{{ if eq $math "" -}}
+<p>$${{- .Inner | safeHTML }}$$</p>
+{{ else -}}
+${{- $math | safeHTML }}$
+{{ end -}}
+
+{{ .Page.Store.Set "hasMath" true }}

netlify.toml

@@ -3,9 +3,9 @@ command = "hugo -b $URL -s exampleSite"
 publish = "exampleSite/public"
 
 [context.production.environment]
-HUGO_VERSION = "0.109.0"
-GO_VERSION = "1.19.4"
+HUGO_VERSION = "0.110.0"
+GO_VERSION = "1.19.5"
 
 [context.deploy-preview.environment]
-HUGO_VERSION = "0.109.0"
-GO_VERSION = "1.19.4"
+HUGO_VERSION = "0.110.0"
+GO_VERSION = "1.19.5"