Allow LaTeX in Markdown using standard syntax (#70)

Co-authored-by: Yihui Xie <xie@yihui.name>

.gitignore

@@ -2,4 +2,5 @@
 .Rhistory
 .RData
 .Ruserdata
+exampleSite/.hugo_build.lock
 exampleSite/public

exampleSite/content/_index.markdown

@@ -33,6 +33,6 @@ I can certainly further reduce the code, for example, by eliminating the CSS, bu
 
 Although it is a minimal theme, it is actually fully functional. It supports pages (including the home page), blog posts, a navigation menu, categories, tags, and RSS. With [a little bit customization](https://github.com/yihui/hugo-xmin/blob/master/exampleSite/layouts/partials/foot_custom.html), it can easily support LaTeX math expressions, e.g.,
 
-`$${\sqrt {n}}\left(\left({\frac {1}{n}}\sum _{i=1}^{n}X_{i}\right)-\mu \right)\ {\xrightarrow {d}}\ N\left(0,\sigma ^{2}\right)$$`
+$${\sqrt {n}}\left(\left({\frac {1}{n}}\sum _{i=1}^{n}X_{i}\right)-\mu \right)\ {\xrightarrow {d}}\ N\left(0,\sigma ^{2}\right)$$
 
 All pages not under the root directory of the website are listed below. You can also visit the list page of a single section, e.g., [posts](/post/), or [notes](/note/). See the [About](/about/) page for the usage of this theme.

exampleSite/content/about.md

@@ -7,7 +7,7 @@ author: Yihui Xie
 
 The theme name "XMin" can be interpreted as "**X**ie's **Min**imal theme" (Xie is my last name) or "e**X**tremely **Min**imal theme".
 
-# config.yaml
+## `hugo.yaml` (the config file)
 
 For this example site, I defined permalinks for two sections, `post` and `note`, so that the links to pages under these directories will contain the date info, e.g., `https://xmin.yihui.org/post/2016/02/14/a-plain-markdown-post/`. This is optional, and it is up to your personal taste of URLs.
 
@@ -49,12 +49,11 @@ params:
 
 Here `{Year}` means the year in which the site is built (usually the current year).
 
-# Custom layouts
+## Custom layouts
 
 There are two layout files under `layouts/partials/` that you may want to override: `head_custom.html` and `foot_custom.html`. This is how you inject arbitrary HTML code to the head and foot areas. For example, this site has a file `layouts/partials/foot_custom.html` to support LaTeX math via KaTeX and center images automatically:
 
 ```html
-<script src="//cdn.jsdelivr.net/npm/@xiee/utils/js/math-code.min.js" defer></script>
 <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex/dist/katex.min.css">
 <script src="//cdn.jsdelivr.net/combine/npm/katex/dist/katex.min.js,npm/katex/dist/contrib/auto-render.min.js,npm/@xiee/utils/js/render-katex.js" defer></script>
 
@@ -65,7 +64,7 @@ You can certainly enable highlight.js for syntax highlighting by yourself throug
 
 If you do not like the default fonts (e.g., `Palatino`), you may provide your own `static/css/fonts.css` under the root directory of your website to override the `fonts.css` in the theme.
 
-# Other features
+## Other features
 
 I could have added more features to this theme, but I decided not to, since I have no intention to make this theme feature-rich. However, I will teach you how. I have prepared several examples via pull requests at https://github.com/yihui/hugo-xmin/pulls, so that you can see the implementations of these features when you check out the diffs in the pull requests. For example, you can:
 

exampleSite/content/post/2016-02-14-hello-markdown.md

@@ -25,29 +25,25 @@ This is a post written in plain Markdown (`*.md`) instead of R Markdown
 1.  You cannot run any R code in a plain Markdown document, whereas in an R
     Markdown document, you can embed R code chunks (```` ```{r} ````);
 2.  A plain Markdown post is rendered through
-    [Blackfriday](https://gohugo.io/overview/configuration/), and an R Markdown
-    document is compiled by [**rmarkdown**](http://rmarkdown.rstudio.com) and
+    [Goldmark](https://gohugo.io/overview/configuration/) by default, and an R
+    Markdown document is compiled by
+    [**rmarkdown**](http://rmarkdown.rstudio.com) and
     [Pandoc](http://pandoc.org).
 
-There are many differences in syntax between Blackfriday's Markdown and Pandoc's
-Markdown. For example, you can write a task list with Blackfriday but not with
-Pandoc:
-
--   [x] Write an R package.
--   [ ] Write a book.
--   [ ] ...
--   [ ] Profit!
-
-Similarly, Blackfriday does not support LaTeX math and Pandoc does. I have added
-the MathJax support to this theme
-([hugo-xmin](https://github.com/yihui/hugo-xmin)) but there is a caveat for
-plain Markdown posts: you have to include math expressions in a pair of
-backticks (inline: `` `$ $` ``; display style: `` `$$ $$` ``), e.g.,
-`$S_n = \sum_{i=1}^n X_i$`.[^1] For R Markdown posts, you do not need the
-backticks, because Pandoc can identify and process math expressions.
-
-[^1]: This is because we have to protect the math expressions from being
-    interpreted as Markdown.
+There are differences in syntax between Goldmark's Markdown and Pandoc's
+Markdown. For example, Goldmark does not support LaTeX math and Pandoc does. I
+have added the KaTeX support to this theme (i.e.,
+[hugo-xmin](https://github.com/yihui/hugo-xmin))
+
+As of Hugo v0.122.0, you can enable typesetting \(\LaTeX\) math in Markdown using
+the standard syntax. To do so, you have make use of the goldmark `passthrough`
+extension inside your config file (e.g., `hugo.yaml`). Afterwards you can use
+standard \(\TeX\) syntax (inline: `\( ... \)`; display style: `$$ ... $$`) to
+display formulae, e.g., \(S_n = \sum_{i=1}^n X_i\). For details, please refer to
+the official [Hugo docs](https://gohugo.io/content-management/mathematics/).
+Alternatively, you may see
+[this post](https://yihui.org/en/2018/07/latex-math-markdown/) for a general
+solution, which works with any Hugo version and requires no configuration.
 
 When creating a new post, you have to decide whether the post format is Markdown
 or R Markdown, and this can be done via the `rmd` argument of the function
@@ -76,9 +72,9 @@ tempor incididunt ut labore et dolore *magna aliqua*. Ut enim ad minim veniam,
 quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
 consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
 dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident,
-sunt in culpa qui officia deserunt mollit anim id est laborum.[^2]
+sunt in culpa qui officia deserunt mollit anim id est laborum.[^1]
 
-[^2]: I'm sure you are bored by the text here.
+[^1]: I'm sure you are bored by the text here.
 
 A blockquote (a gray bar at the left and lightgray background):
 

exampleSite/config.yaml → exampleSite/hugo.yaml

@@ -38,3 +38,15 @@ markup:
   goldmark:
     renderer:
       unsafe: true
+    extensions:
+      passthrough:
+        enable: true
+        delimiters:
+          block:
+          - - \[
+            - \]
+          - - $$
+            - $$
+          inline:
+          - - \(
+            - \)

exampleSite/layouts/partials/foot_custom.html

@@ -1,4 +1,3 @@
-<script src="//cdn.jsdelivr.net/npm/@xiee/utils/js/math-code.min.js" defer></script>
 <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex/dist/katex.min.css">
 <script src="//cdn.jsdelivr.net/combine/npm/katex/dist/katex.min.js,npm/katex/dist/contrib/auto-render.min.js,npm/@xiee/utils/js/render-katex.js" defer></script>