Allow LaTeX in Markdown using standard syntax (#70)

Co-authored-by: Yihui Xie <xie@yihui.name>
This commit is contained in:
Andreas Deininger 2024-03-04 03:20:29 +01:00 committed by GitHub
parent d7763268b4
commit b76b60eb94
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 35 additions and 28 deletions

1
.gitignore vendored
View file

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

View file

@ -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.

View file

@ -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:

View file

@ -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):

View file

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

View file

@ -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>