gatsby: [gatsby-remark-katex] Doesn’t work with gatsby-plugin-mdx

@jannikbuschke

It seems this is not properly documented yet and maybe the root issue is not yet resolved?

Unfortunately not yet. The root issue is that remark-math which is a core dependency of gatsby-remark-katex requires remark 13 to get working.

However then it seems to need updating @mdx-js/mdx to 2.0.0 first and it’d be a bit heavy work to get done.

is the way it should work, but does not?

I agree with you. It should work unless such incompatibility. But thus we need some workaround for right now.

Since it’s not a specific issue only with gatsby-remark-katex but more about general version compatibility, it maybe more helpful if it was somehow documented.

Workaround

FYI, here is the workaround to enable KaTeX with gatsby-plugin-mdx.

There are two points.

1. use remark-math and rehype-katex insted of gatsby-remark-katex
2. explicitly specify compatible version of each

Version

gatsby@4.9.3 gatsby-plugin-mdx@3.9.1

Snippet

npm install remark-math@3.0.1 rehype-katex@5.0.0

gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
        remarkPlugins: [
          require('remark-math'),
        ],
        rehypePlugins: [
          [require('rehype-katex'), { strict: 'ignore' }],
        ],
      }
    }
  ]
}

gatsby-browser.js

import 'katex/dist/katex.min.css'

Note that katex module comes with rehype-katex therefor it doesn’t have to be installed individually.

I tried it with the latest versions and the problem remains. Here’s my package.json:

{
  "dependencies": {
    "@mdx-js/mdx": "^1.6.5",
    "@mdx-js/react": "^1.6.5",
    "gatsby": "^2.23.0",
    "gatsby-plugin-mdx": "^1.2.14",
    "gatsby-remark-katex": "^3.3.3",
    "gatsby-source-filesystem": "^2.3.10",
    "katex": "^0.11.1",
    "react": "^16.13.1",
    "react-dom": "^16.13.1"
  }
}

To try it for yourself, just use this package.json on the original doesnt-work reproduction project I posted in my original message.

It seems this is not properly documented yet and maybe the root issue is not yet resolved?

When digging through this thread I also faced issues with the recommend solutions, i.e. require(‘remark-math’), as require is not allowed.

And the different plugins (remark-math, remark-html-katex, gatsby-remark-katex, rehype-katex) also confuse me.

Am I assuming correct, that what is currently documented

// doesnt-work
$ npm install gatsby-transformer-remark gatsby-remark-katex katex

// gatsby-config.js
{
  resolve: `gatsby-plugin-mdx`,
  options: {
    gatsbyRemarkPlugins: [`gatsby-remark-katex`]
  }
}

is the way it should work, but does not?

@tnorlund @princefishthrower

What’s your gatsby-config look like with these packages?

// gatsby-config.js
{
    resolve: 'gatsby-plugin-mdx',
    options: {
      extensions: ['.mdx', '.md'],
      remarkPlugins: [
        require('../../plugins/remark-element-directive'),
        // require('remark-images'),
        require('remark-math'),
        require('remark-emoji'),
      ],
      rehypePlugins: [
        require('rehype-katex'),
      ],
      gatsbyRemarkPlugins: [
        {
          resolve: 'gatsby-remark-autolink-headers',
          options: {
            // offsetY: '100',
            icon: false,
            // icon: '<svg aria-hidden="true" height="20" version="1.1" viewBox="0 0 16 16" width="20"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>',
            // maintainCase: true,
            // removeAccents: true,
            isIconAfterHeader: false,
            elements: ['h2'],
          },
        },
      ],
    },
  },

// package.json
...
    "@mdx-js/mdx": "^1.6.22",
    "@mdx-js/react": "^1.6.22",
    "gatsby": "^3.1.0",
    "gatsby-plugin-mdx": "^2.1.0",
    "remark-html-katex": "^3.0.0",
   "remark-math": "^3.0.1",
...

What ended fixing the problem for me (march/2021 - "gatsby": "^3.1.0", "gatsby-plugin-mdx": "^2.1.0", ) was explicitly including an older version of "remark-math": "^3.0.1", instead of the latest version which is 4 version 4 relies on the newest version of remark with all of the newest bells and whistles, while gatsby-plugin-mdx still relies on remark v12. I hope this helps someone.

@ehowey could you please mention how did you get it working? The work around is not working correctly for me and instead outputs both the html and the mathml side by side.

I believe that’s the intended HTML output. You may be missing the CSS, which hides one of the two depending on the browser’s capabilities.

Hmm, funny. I have had this issue before and was using the workaround for a while. Not sure what has changed since then but the usual instructions work for me now

In gatsby-config.js,

    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        gatsbyRemarkPlugins: [
          {
            resolve: `gatsby-remark-katex`,
            options: {
              strict: `ignore`,
            },
          },
       }
    }

and in gatsby-browser.js

import "katex/dist/katex.min.css"

For someone who wants to inspect further, the complete source is here.

@danedavid: Here’s what I’d start with:

1. Setup the local development environment.

2. Modify the sample website doesnt-work that I included in this issue to use the local Gatsby installation. (Use npm link.)

3. Check that the remark-math parser plugin is being picked up. I’d modify the line to read something like:

module.exports.setParserPlugins = () => { console.log("PLUGIN IS BEING PICKED UP"); return [remarkMath]; }

1. Check that the gatsby-remark-katex plugin itself is being picked up. I’d add a console.log() there as well.

2. Check that the visitors are finding the math nodes and producing appropriate results.

I’d expect the problem to become evident somewhere along this process.

Warning: Take what I’m saying with a grain of salt, as I’ve never contributed to the Gatsby codebase myself.

For What It’s Worth, this is the setup that worked for me:

Dependencies:

"gatsby": "^5.12.4",
"remark-math": "^5.1.1",
"rehype-katex": "^6.0.3",

Gatsby Configuration:

{
  resolve: `gatsby-plugin-mdx`,
  options: {
    mdxOptions: {
      remarkPlugins: [remarkMath],
      rehypePlugins: [
        [rehypeKatex, { strict: 'ignore' }],
      ],
    },
  },
}

Example in .mdx:

import 'katex/dist/katex.min.css'

$$
x = \frac{{-b \pm \sqrt{{b^2 - 4ac}}}}{{2a}}
$$

The formula \( a + b = 2 \) tells us something important.

This is what I have so far. It works, but I cannot write ‘complex’ equations.

// gatsby-config.js
const remark_math = require( `remark-math` )
const remark_html_katex = require( `remark-html-katex` )

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        gatsbyRemarkPlugins: [
          {
            resolve: `gatsby-remark-katex`,
            options: {
              strict: `ignore`,
            }
          },
        ],
        remarkPlugins: [ remark_math, remark_html_katex ],
        extensions: [`.md`, `.mdx`],
      },
    },

@tnorlund @princefishthrower I had the same problem and here’s the package versions I used and my gatsby-config.js. Hope it helps!