From a960734e6f152d967405bde6e4718daf257043f0 Mon Sep 17 00:00:00 2001
From: Egor Tensin <Egor.Tensin@gmail.com>
Date: Mon, 30 Sep 2019 01:37:50 +0300
Subject: work around GitHub limitations for MathJax support

---
 README.md                               | 27 +++++++++++++++++++++------
 _config.yml                             |  2 +-
 _includes/common/mathjax.html           |  2 +-
 _includes/common/mathjax_workaround.md  |  1 +
 _posts/2019-09-30-recurring-decimals.md |  4 +++-
 5 files changed, 27 insertions(+), 9 deletions(-)
 create mode 100644 _includes/common/mathjax_workaround.md

diff --git a/README.md b/README.md
index 67d35f2..68da3b5 100644
--- a/README.md
+++ b/README.md
@@ -75,14 +75,29 @@ y = kx + b
 $$
 ```
 
+[MathJax]: https://www.mathjax.org/
+
+#### GitHub workarounds
+
 MathJax version 3 is used, which is unsupported by Kramdown (which produces
-`<script type="math/tex; ..."` tags, suitable for MathJax 2.
+`<script type="math/tex; ..."` tags, suitable only for MathJax 2.
 This is why `math_engine` is set to `null` in _config.yml, making Kramdown
-output block formulas wrapped in `$$` and inline formulas in `$` respectively.
-MathJax is additionally customized to recognize `$` as an inline formula
-delimiter in _includes/common/mathjax.html.
-
-[MathJax]: https://www.mathjax.org/
+output block formulas wrapped in `$$` and inline formulas in `$` respectively
+([inside `<span class="kdmath">` elements][kramdown issue]).
+Because if this, MathJax is additionally customized to recognize `$` as an
+inline formula delimiter in _includes/common/mathjax.html.
+
+GitHub Pages [helpfully overrides] the `math_engine` setting in your
+_config.yml, hardcoding it to `mathjax` instead of `null` (there's a related
+[pull request]).
+I couldn't find a better way than to override the setting in the markdown
+document itself using
+
+    {::options math_engine="+nil+" /}
+
+[kramdown issue]: https://github.com/gettalong/kramdown/issues/342
+[helpfully overrides]: https://help.github.com/en/articles/configuring-jekyll
+[pull request]: https://github.com/github/pages-gem/pull/644
 
 License
 -------
diff --git a/_config.yml b/_config.yml
index c6d3334..b3dc57b 100644
--- a/_config.yml
+++ b/_config.yml
@@ -22,7 +22,7 @@ highlighter: rouge
 markdown: kramdown
 
 kramdown:
-  math_engine: null
+  math_engine: null # Ignored by GitHub Pages, yay, how fun!
   syntax_highlighter_opts:
     span:
       disable: true
diff --git a/_includes/common/mathjax.html b/_includes/common/mathjax.html
index 1d59f37..7110f57 100644
--- a/_includes/common/mathjax.html
+++ b/_includes/common/mathjax.html
@@ -1,6 +1,6 @@
 {% if page.mathjax %}
   <script>
-// See the README for explanation:
+// See the README.md for explanation:
 MathJax = {
   tex: {
     inlineMath: [['$', '$']]
diff --git a/_includes/common/mathjax_workaround.md b/_includes/common/mathjax_workaround.md
new file mode 100644
index 0000000..9d0a77d
--- /dev/null
+++ b/_includes/common/mathjax_workaround.md
@@ -0,0 +1 @@
+{::options math_engine="+nil+" /}
diff --git a/_posts/2019-09-30-recurring-decimals.md b/_posts/2019-09-30-recurring-decimals.md
index 83d949c..1151c19 100644
--- a/_posts/2019-09-30-recurring-decimals.md
+++ b/_posts/2019-09-30-recurring-decimals.md
@@ -6,6 +6,8 @@ excerpt: >
 category: Math
 mathjax: true
 ---
+{% include common/mathjax_workaround.md %}
+
 First, let's determine that
 
 $$
@@ -21,7 +23,7 @@ $$
 0.(9) = 1
 $$
 
-This is counter-intuitive, but demonstrably true.
+This may seem counter-intuitive, but demonstrably true.
 If $$0.(9) \neq 1$$, then $$\exists n \in \reals: 0.(9) < n < 1$$.
 To put it another way, there must be a number greater than 0.(9) and lesser
 than 1, equal to neither.
-- 
cgit v1.2.3