Use Gatsbyjs with MDX and Latex Equations

I am using Gatsbyjs for a while and really love it to generate static sites. With the help of gatsby-transformer-remark plugin, It is a pleasure to transform Markdown files to HTML. I built a documentation site in production and this blog site for personal use, they both run well and serve their own purposes.

However, the whole content will depend on Markdown syntax, which was invented to be simple. It wasn’t enough for some people, many new features were added to Markdown like flow chart support, latex equation support, table support, etc. While those features are indeed helpful in someway and make it easier to write beautiful document in text format. There is still no Markdown standard and almost every Markdown editor has its own rendering rules.

I chose markdown in the first place for its simplicity. Now I have to bear with markdown file generated in one place may not render correctly in another place, or stick with basic syntax that lack of features I need. Fortunately, MDX comes to the rescue. MDX lets us write JSX embedded inside markdown. It’s a great combination that allows us to use markdown’s terse syntax for the little things and JSX for more advanced components.

I updated my site to use MDX file as template for HTML generation, it works seamlessly as I set it to backwards compatible with md files. The PIA is that it doesn’t support latex out of box. Of course I can transfer latex to html or JSX block then embed it in markdown file. That’s ok for occasionally use but too much for many equations. I couldn’t find a perfect solution for my need and spent some time to make it work.

The goal is when we type latex in a $$ latex $$ block like this in a md or mdx file:

1

Mean = \frac{10 + 14+ 7 +23+ 23+ 15 + 7 + 23 + 32}{9} = \frac{154}{9} \approx 17.11

The following will be rendered in the end: $$ Mean = \frac{10 + 14+ 7 +23+ 23+ 15 + 7 + 23 + 32}{9} = \frac{154}{9} \approx 17.11 $$ gatsby-plugin-mdx is the official integration for using MDX with Gatsby.

Install with npm:

1

npm install gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

Or install with yarn:

1

yarn add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

Then we need remark-math and rehype-katex to render math blocks. remark-math parses math blocks and rehype-katex transforms math blocks into html elements with classes for styling.

Install those two packages via npm:

1
2

npm install remark-math --save
npm install rehype-katex --save

1
2
3
4

//template-blog-post.js 
//...
import "katex/dist/katex.min.css"
//...

Then we need config gatsby-plugin-mdx to work with remark-math and rehype-katex. My gatsby-config.js file look like this in then end. gatsby-remark-images part can be omitted.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

//gatsby-config.js
const remarkMath = require('remark-math')
const rehypeKatex = require('rehype-katex')

module.exports = {
  // ...
  plugins: [
    // ...
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        extensions: [`.mdx`, `.md`],
        remarkPlugins: [remarkMath],
        rehypePlugins: [rehypeKatex],
        gatsbyRemarkPlugins: [
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 960,
              quality: 90,
              linkImagesToOriginal: false,
            },
          },
        ],
      },
    },
   ],
}

References:

https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx

https://mdxjs.com/guides/math-blocks

https://github.com/gatsbyjs/gatsby/blob/master/examples/using-remark/src/templates/template-blog-post.js