From 67aa482ff6b2ebb0626a3710458fa774e61926bc Mon Sep 17 00:00:00 2001
From: James Panther <4462786+jpanther@users.noreply.github.com>
Date: Thu, 4 Nov 2021 10:08:59 +1100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20mathematical=20notation=20?=
=?UTF-8?q?docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
exampleSite/content/docs/shortcodes.md | 20 ++++++++
.../content/samples/math-typesetting.md | 47 -------------------
.../content/samples/mathematical-notation.md | 46 ++++++++++++++++++
3 files changed, 66 insertions(+), 47 deletions(-)
delete mode 100755 exampleSite/content/samples/math-typesetting.md
create mode 100755 exampleSite/content/samples/mathematical-notation.md
diff --git a/exampleSite/content/docs/shortcodes.md b/exampleSite/content/docs/shortcodes.md
index 63801d01..cd059f93 100644
--- a/exampleSite/content/docs/shortcodes.md
+++ b/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
+{{}}
+\\(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.
diff --git a/exampleSite/content/samples/math-typesetting.md b/exampleSite/content/samples/math-typesetting.md
deleted file mode 100755
index 086b6805..00000000
--- a/exampleSite/content/samples/math-typesetting.md
+++ /dev/null
@@ -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.
-
-
-
-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)
-
-
-
-
-
-
-### Examples
-
-
-
-Block math:
-
-$$
- \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }
-$$
diff --git a/exampleSite/content/samples/mathematical-notation.md b/exampleSite/content/samples/mathematical-notation.md
new file mode 100755
index 00000000..d48e09d0
--- /dev/null
+++ b/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.
+
+
+
+{{< 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} } }
+$$