✨ Add KaTeX and katex shortcode

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Added
 
 - Chart.js support using `chart` shortcode
+- KaTeX support using `katex` shortcode
 - Dark mode toggle with new theme parameters for managing light/dark appearance
 - French translation ([#18](https://github.com/jpanther/congo/pull/18))
 - Grouping by year can now be specificed in front matter on list pages
@@ -23,6 +24,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Site logo image dimensions are unconstrained ([#19](https://github.com/jpanther/congo/issues/19))
 - Article summary styled incorrectly in dark mode
+- Links containing `code` blocks styled incorrectly
 
 ## [1.4.0] - 2021-10-20
 

assets/css/compiled/main.css

@@ -787,7 +787,7 @@ video {
 }
 
 .prose a code {
-  color: #111827;
+  color: var(--color-secondary-700);
 }
 
 .prose pre {
@@ -2457,6 +2457,11 @@ body a, body button {
           text-decoration-color: var(--color-neutral-500);
 }
 
+.dark .dark\:prose-light a:hover {
+  color: var(--color-neutral);
+  text-decoration: none;
+}
+
 .dark .dark\:prose-light strong {
   color: var(--color-neutral);
 }
@@ -2503,7 +2508,7 @@ body a, body button {
 }
 
 .dark .dark\:prose-light a code {
-  color: var(--color-neutral);
+  color: var(--color-secondary-400);
 }
 
 .dark .dark\:prose-light pre {

assets/vendor/katex/auto-render.min.js

@@ -0,0 +1 @@
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("katex")):"function"==typeof define&&define.amd?define(["katex"],t):"object"==typeof exports?exports.renderMathInElement=t(require("katex")):e.renderMathInElement=t(e.katex)}("undefined"!=typeof self?self:this,(function(e){return function(){"use strict";var t={771:function(t){t.exports=e}},r={};function n(e){var a=r[e];if(void 0!==a)return a.exports;var i=r[e]={exports:{}};return t[e](i,i.exports,n),i.exports}n.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(t,{a:t}),t},n.d=function(e,t){for(var r in t)n.o(t,r)&&!n.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:t[r]})},n.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)};var a={};return function(){n.d(a,{default:function(){return s}});var e=n(771),t=n.n(e),r=function(e,t,r){for(var n=r,a=0,i=e.length;n<t.length;){var o=t[n];if(a<=0&&t.slice(n,n+i)===e)return n;"\\"===o?n++:"{"===o?a++:"}"===o&&a--,n++}return-1},i=/^\\begin{/,o=function(e,t){for(var n,a=[],o=new RegExp("("+t.map((function(e){return e.left.replace(/[-/\\^$*+?.()|[\]{}]/g,"\\$&")})).join("|")+")");-1!==(n=e.search(o));){n>0&&(a.push({type:"text",data:e.slice(0,n)}),e=e.slice(n));var l=t.findIndex((function(t){return e.startsWith(t.left)}));if(-1===(n=r(t[l].right,e,t[l].left.length)))break;var d=e.slice(0,n+t[l].right.length),s=i.test(d)?d:e.slice(t[l].left.length,n);a.push({type:"math",data:s,rawData:d,display:t[l].display}),e=e.slice(n+t[l].right.length)}return""!==e&&a.push({type:"text",data:e}),a},l=function(e,r){var n=o(e,r.delimiters);if(1===n.length&&"text"===n[0].type)return null;for(var a=document.createDocumentFragment(),i=0;i<n.length;i++)if("text"===n[i].type)a.appendChild(document.createTextNode(n[i].data));else{var l=document.createElement("span"),d=n[i].data;r.displayMode=n[i].display;try{r.preProcess&&(d=r.preProcess(d)),t().render(d,l,r)}catch(e){if(!(e instanceof t().ParseError))throw e;r.errorCallback("KaTeX auto-render: Failed to parse `"+n[i].data+"` with ",e),a.appendChild(document.createTextNode(n[i].rawData));continue}a.appendChild(l)}return a},d=function e(t,r){for(var n=0;n<t.childNodes.length;n++){var a=t.childNodes[n];if(3===a.nodeType){var i=l(a.textContent,r);i&&(n+=i.childNodes.length-1,t.replaceChild(i,a))}else 1===a.nodeType&&function(){var t=" "+a.className+" ";-1===r.ignoredTags.indexOf(a.nodeName.toLowerCase())&&r.ignoredClasses.every((function(e){return-1===t.indexOf(" "+e+" ")}))&&e(a,r)}()}},s=function(e,t){if(!e)throw new Error("No element provided to render");var r={};for(var n in t)t.hasOwnProperty(n)&&(r[n]=t[n]);r.delimiters=r.delimiters||[{left:"$$",right:"$$",display:!0},{left:"\\(",right:"\\)",display:!1},{left:"\\begin{equation}",right:"\\end{equation}",display:!0},{left:"\\begin{align}",right:"\\end{align}",display:!0},{left:"\\begin{alignat}",right:"\\end{alignat}",display:!0},{left:"\\begin{gather}",right:"\\end{gather}",display:!0},{left:"\\begin{CD}",right:"\\end{CD}",display:!0},{left:"\\[",right:"\\]",display:!0}],r.ignoredTags=r.ignoredTags||["script","noscript","style","textarea","pre","code","option"],r.ignoredClasses=r.ignoredClasses||[],r.errorCallback=r.errorCallback||console.error,r.macros=r.macros||{},d(e,r)}}(),a=a.default}()}));

exampleSite/content/docs/shortcodes.md

@@ -111,6 +111,26 @@ Icons are populated using Hugo pipelines which makes them very flexible. Congo s
 
 Icons can also be used in partials by calling the [icon partial]({{< ref "partials#icon" >}}).
 
+## Katex
+
+The `katex` shortcode can be used to add mathematical expressions to article content using the KaTeX package. Refer to the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax.
+
+To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported.
+
+Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.
+
+**Example:**
+
+```md
+{{</* katex */>}}
+\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+```
+
+{{< katex >}}
+\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+
+Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}}) page for more examples.
+
 ## Lead
 
 `lead` is used to bring emphasis to the start of an article. It can be used to style an introduction, or to call out an important piece of information. Simply wrap any Markdown content in the `lead` shortcode.

exampleSite/content/samples/math-typesetting.md

@@ -1,47 +0,0 @@
----
-author: Hugo Authors
-title: Math Typesetting
-date: 2019-03-08
-description: A brief guide to setup KaTeX
-math: true
-tags: ["sample"]
----
-
-Mathematical notation in a Hugo project can be enabled by using third party JavaScript libraries.
-
-<!--more-->
-
-In this example we will be using [KaTeX](https://katex.org/).
-
-- Create a partial under `/layouts/partials/math.html`
-- Within this partial reference the [Auto-render Extension](https://katex.org/docs/autorender.html) or host these scripts locally.
-- Include the partial in your templates like so:
-
-```bash
-{{ if or .Params.math .Site.Params.math }}
-{{ partial "math.html" . }}
-{{ end }}
-```
-
-- 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
-
-**Note:** Use the online reference of [Supported TeX Functions](https://katex.org/docs/supported.html)
-
-<!-- KaTeX -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/katex.min.css" integrity="sha384-RZU/ijkSsFbcmivfdRBQDtwuwVqK7GMOw6IMvKyeWL2K5UAlyp6WonmB8m7Jd0Hn" crossorigin="anonymous">
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/katex.min.js" integrity="sha384-pK1WpvzWVBQiP0/GjnvRxV4mOb0oxFuyRxJlk6vVw146n3egcN5C925NCP7a7BY8" crossorigin="anonymous"></script>
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/contrib/auto-render.min.js" integrity="sha384-vZTG03m+2yp6N6BNi5iM4rW4oIwk5DfcNdFfxkk9ZWpDriOkXX8voJBFrAO7MpVl" crossorigin="anonymous"
-    onload="renderMathInElement(document.body);"></script>
-
-### Examples
-
-<p>
-Inline math: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
-</p>
-
-Block math:
-
-$$
- \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
-$$

exampleSite/content/samples/mathematical-notation.md

@@ -0,0 +1,46 @@
+---
+title: Mathematical notation
+date: 2019-03-08
+description: A brief sample of mathematical notation in Congo.
+tags: ["sample", "katex", "maths"]
+---
+
+KaTeX can be used to render mathematical notation within articles.
+
+<!--more-->
+
+{{< katex >}}
+
+Congo will only bundle the KaTeX assets into your project if you make use of mathematical notation. In order for this to work, simply include the [`katex` shortcode]({{< ref "docs/shortcodes#katex" >}}) within the article. Any KaTeX syntax on that page will then be automatically rendered.
+
+Use the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax.
+
+## Inline notation
+
+Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters.
+
+**Example:**
+
+```tex
+% KaTeX inline notation
+Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+```
+
+Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+
+## Block notation
+
+Alternatively, block notation can be generated using `$$` delimiters. This will output the expression in its own HTML block.
+
+**Example:**
+
+```tex
+% KaTeX block notation
+$$
+ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
+$$
+```
+
+$$
+ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
+$$

layouts/partials/vendor.html

@@ -1,7 +1,6 @@
 {{/* Mermaid */}}
 {{ if .Page.HasShortcode "mermaid" }}
   {{ $mermaidJS := resources.Get "vendor/mermaid/mermaid.min.js" }}
-  {{ if $mermaidJS }}
   {{ $mermaidJS := $mermaidJS | resources.Fingerprint "sha512" }}      <script defer src="{{ $mermaidJS.RelPermalink }}" integrity="{{ $mermaidJS.Data.Integrity }}"></script>
   <script>
     document.addEventListener('DOMContentLoaded', (event) => {
@@ -11,12 +10,10 @@
       mermaid.initialize({ theme: "base", themeVariables: { background: css("--color-neutral"), primaryColor: css("--color-primary-200"), secondaryColor: css("--color-secondary-200"), tertiaryColor: css("--color-neutral-100"), primaryBorderColor: css("--color-primary-400"), secondaryBorderColor: css("--color-secondary-400"), tertiaryBorderColor: css("--color-neutral-400"), lineColor: css("--color-neutral-600"), fontFamily: "ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,segoe ui,Roboto,helvetica neue,Arial,noto sans,sans-serif", fontSize: "16px" }});
     });
   </script>
-  {{ end }}
 {{ end }}
 {{/* Chart */}}
 {{ if .Page.HasShortcode "chart" }}
   {{ $chartJS := resources.Get "vendor/chart/chart.min.js" }}
-  {{ if $chartJS }}
   {{ $chartJS := $chartJS | resources.Fingerprint "sha512" }}
   <script defer src="{{ $chartJS.RelPermalink }}" integrity="{{ $chartJS.Data.Integrity }}"></script>
   <script>
@@ -35,5 +32,24 @@
       Chart.defaults.elements.arc.borderWidth = 1;
     });
   </script>
+{{ end }}
+{{/* Katex */}}
+{{ if .Page.HasShortcode "katex" }}
+  {{ $katexCSS := resources.Get "vendor/katex/katex.min.css" }}
+  {{ $katexCSS := $katexCSS | resources.Fingerprint "sha512" }}
+  <link
+    type="text/css" rel="stylesheet"
+    href="{{ $katexCSS.RelPermalink }}"
+    integrity="{{ $katexCSS.Data.Integrity }}"
+  />
+  {{ $katexJS := resources.Get "vendor/katex/katex.min.js" }}
+  {{ $katexJS := $katexJS | resources.Fingerprint "sha512" }}
+  <script defer src="{{ $katexJS.RelPermalink }}" integrity="{{ $katexJS.Data.Integrity }}"></script>
+  {{ $katexRenderJS := resources.Get "vendor/katex/auto-render.min.js" }}
+  {{ $katexRenderJS := $katexRenderJS | resources.Fingerprint "sha512" }}
+  <script defer src="{{ $katexRenderJS.RelPermalink }}" integrity="{{ $katexRenderJS.Data.Integrity }}" onload="renderMathInElement(document.body);"></script>
+  {{ $katexFonts := resources.Match "vendor/katex/fonts/*" }}
+  {{ range $katexFonts }}
+    <!-- {{ .RelPermalink }} -->
   {{ end }}
 {{ end }}

layouts/shortcodes/katex.html

@@ -0,0 +1 @@
+{{/* Nothing to see here */}}

package-lock.json

@@ -12,6 +12,7 @@
       "devDependencies": {
         "@tailwindcss/typography": "^0.4.1",
         "chart.js": "^3.6.0",
+        "katex": "^0.15.1",
         "mermaid": "^8.13.3",
         "prettier": "^2.3.2",
         "prettier-plugin-go-template": "^0.0.11",
@@ -1755,6 +1756,31 @@
         "graceful-fs": "^4.1.6"
       }
     },
+    "node_modules/katex": {
+      "version": "0.15.1",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.15.1.tgz",
+      "integrity": "sha512-KIk+gizli0gl1XaJlCYS8/donGMbzXYTka6BbH3AgvDJTOwyDY4hJ+YmzJ1F0y/3XzX5B9ED8AqB2Hmn2AZ0uA==",
+      "dev": true,
+      "funding": [
+        "https://opencollective.com/katex",
+        "https://github.com/sponsors/katex"
+      ],
+      "dependencies": {
+        "commander": "^8.0.0"
+      },
+      "bin": {
+        "katex": "cli.js"
+      }
+    },
+    "node_modules/katex/node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "dev": true,
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/khroma": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/khroma/-/khroma-1.4.1.tgz",
@@ -3936,6 +3962,23 @@
         "universalify": "^2.0.0"
       }
     },
+    "katex": {
+      "version": "0.15.1",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.15.1.tgz",
+      "integrity": "sha512-KIk+gizli0gl1XaJlCYS8/donGMbzXYTka6BbH3AgvDJTOwyDY4hJ+YmzJ1F0y/3XzX5B9ED8AqB2Hmn2AZ0uA==",
+      "dev": true,
+      "requires": {
+        "commander": "^8.0.0"
+      },
+      "dependencies": {
+        "commander": {
+          "version": "8.3.0",
+          "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+          "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+          "dev": true
+        }
+      }
+    },
     "khroma": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/khroma/-/khroma-1.4.1.tgz",

package.json

@@ -30,6 +30,7 @@
   "devDependencies": {
     "@tailwindcss/typography": "^0.4.1",
     "chart.js": "^3.6.0",
+    "katex": "^0.15.1",
     "mermaid": "^8.13.3",
     "prettier": "^2.3.2",
     "prettier-plugin-go-template": "^0.0.11",
@@ -38,7 +39,8 @@
     "tailwindcss": "^2.2.17",
     "vendor-copy": "^3.0.1"
   },
-  "vendorCopy": [
+  "vendorCopy": [],
+  "devVendorCopy": [
     {
       "from": "node_modules/mermaid/dist/mermaid.min.js",
       "to": "assets/vendor/mermaid/mermaid.min.js"
@@ -46,6 +48,22 @@
     {
       "from": "node_modules/chart.js/dist/chart.min.js",
       "to": "assets/vendor/chart/chart.min.js"
+    },
+    {
+      "from": "node_modules/katex/dist/katex.min.js",
+      "to": "assets/vendor/katex/katex.min.js"
+    },
+    {
+      "from": "node_modules/katex/dist/katex.min.css",
+      "to": "assets/vendor/katex/katex.min.css"
+    },
+    {
+      "from": "node_modules/katex/dist/contrib/auto-render.min.js",
+      "to": "assets/vendor/katex/auto-render.min.js"
+    },
+    {
+      "from": "node_modules/katex/dist/fonts/",
+      "to": "assets/vendor/katex/fonts/"
     }
   ]
 }

tailwind.config.js

@@ -111,6 +111,9 @@ module.exports = {
               code: {
                 color: theme("colors.secondary.700"),
               },
+              "a code": {
+                color: theme("colors.secondary.700"),
+              },
               "pre code": {
                 color: theme("colors.neutral.700"),
               },
@@ -150,6 +153,10 @@ module.exports = {
               a: {
                 color: theme("colors.primary.400"),
                 textDecorationColor: theme("colors.neutral.500"),
+                "&:hover": {
+                  color: theme("colors.neutral.DEFAULT"),
+                  textDecoration: "none",
+                },
               },
               strong: {
                 color: theme("colors.neutral.DEFAULT"),
@@ -186,7 +193,7 @@ module.exports = {
                 color: theme("colors.secondary.400"),
               },
               "a code": {
-                color: theme("colors.neutral.DEFAULT"),
+                color: theme("colors.secondary.400"),
               },
               pre: {
                 color: theme("colors.neutral.200"),