From b76b60eb943627a8d763e6095c19561315140f69 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Mon, 4 Mar 2024 03:20:29 +0100 Subject: [PATCH] Allow LaTeX in Markdown using standard syntax (#70) Co-authored-by: Yihui Xie --- .gitignore | 1 + exampleSite/content/_index.markdown | 2 +- exampleSite/content/about.md | 7 ++-- .../content/post/2016-02-14-hello-markdown.md | 40 +++++++++---------- exampleSite/{config.yaml => hugo.yaml} | 12 ++++++ exampleSite/layouts/partials/foot_custom.html | 1 - 6 files changed, 35 insertions(+), 28 deletions(-) rename exampleSite/{config.yaml => hugo.yaml} (80%) diff --git a/.gitignore b/.gitignore index ce130a0..a057323 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ .Rhistory .RData .Ruserdata +exampleSite/.hugo_build.lock exampleSite/public diff --git a/exampleSite/content/_index.markdown b/exampleSite/content/_index.markdown index 912e4c6..7d38d25 100644 --- a/exampleSite/content/_index.markdown +++ b/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. diff --git a/exampleSite/content/about.md b/exampleSite/content/about.md index ed326c0..d905e87 100644 --- a/exampleSite/content/about.md +++ b/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 - @@ -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: diff --git a/exampleSite/content/post/2016-02-14-hello-markdown.md b/exampleSite/content/post/2016-02-14-hello-markdown.md index 8e08469..158e526 100644 --- a/exampleSite/content/post/2016-02-14-hello-markdown.md +++ b/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: +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)) -- [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. +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): diff --git a/exampleSite/config.yaml b/exampleSite/hugo.yaml similarity index 80% rename from exampleSite/config.yaml rename to exampleSite/hugo.yaml index 035fac3..b933d55 100644 --- a/exampleSite/config.yaml +++ b/exampleSite/hugo.yaml @@ -38,3 +38,15 @@ markup: goldmark: renderer: unsafe: true + extensions: + passthrough: + enable: true + delimiters: + block: + - - \[ + - \] + - - $$ + - $$ + inline: + - - \( + - \) diff --git a/exampleSite/layouts/partials/foot_custom.html b/exampleSite/layouts/partials/foot_custom.html index 33f384a..d8a992a 100644 --- a/exampleSite/layouts/partials/foot_custom.html +++ b/exampleSite/layouts/partials/foot_custom.html @@ -1,4 +1,3 @@ -