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

[leafac]

Description

I followed the instructions to install gatsby-remark-katex on a website using gatsby-plugin-mdx and it didn’t work. No errors, no nothing, it just didn’t transform the LaTeX in the Markdown.

Steps to reproduce

In this zip there are two projects:

doesnt-work: This is a minimal project to show the issue. To create this project I just followed the instructions to install gatsby-remark-katex.

works: This is a workaround I found based on this comment and the documentation for remark-math, in which they suggest to use rehype-katex instead of remark-html-katex.

You can run the projects with the usual npm install && npx gatsby develop and visit http://localhost:8000.

In summary, the difference is instead of:

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

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

you do:

// works
$ npm install remark-math rehype-katex katex

// gatsby-config.js
{
  resolve: `gatsby-plugin-mdx`,
  options: {
    remarkPlugins: [require(`remark-math`)],
    rehypePlugins: [require(`rehype-katex`)]
  }
}

Expected result

The LaTeX in the Markdown should be rendered.

Actual result

The LaTeX in the Markdown appears unmodified.

Environment

System:
  OS: macOS 10.15.3
  CPU: (4) x64 Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz
  Shell: 5.7.1 - /bin/zsh
Binaries:
  Node: 13.7.0 - /usr/local/bin/node
  npm: 6.14.1 - /usr/local/bin/npm
Languages:
  Python: 2.7.16 - /usr/bin/python
Browsers:
  Chrome: 80.0.3987.122
  Safari: 13.0.5

[github-actions[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[danedavid]

Hey, I'd like to take a shot at this as my first contribution to the gatsby codebase. Been looking into how plugins work in the past days. Need to invest more time over the weekend. Meanwhile, any tips anyone?

[leafac]

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

[danedavid]

I looked into this. It appears the plugin is picked up. It looks like the issue is with the generated markdownAST. When I console.log(markdownAST) inside the gatsby-remark-plugin, the AST does not contain any inlineMath node. But when I check in GraphiQL with query:

{
  allMdx {
    edges {
      node {
        mdxAST
      }
    }
  }
}

the result AST _has_ an inlineMath node. The issue then could be parser not being picked up, but I did do step 3 of @leafac 's comment, and the log showed up.

I also put logs inside visit callback. The logs are not appearing when the pages are built, but logs show (including the correct generated HTML) when I run the query in GraphiQL.

[leafac]

Could it be that gatsby-plugin-mdx isn’t using the mdxAST field, but something like the body field?

[danedavid]

Finally got time, and fixed it. The issue was with mdx-loader used by webpack not picking up gatsby remark parsers. Thank you @leafac for your support!

[danabrit]

@leafac Can you please confirm whether this PR - https://github.com/gatsbyjs/gatsby/pull/21861 - resolved your issue?

[leafac]

What’s the best way for me to check?

I tried to clone https://github.com/jlkiri/gatsby/, switch to the mdx-interop-default-exp branch, go to packages/gatsby-plugin-mdx/ directory, run npm install && npm link, go to my doesnt-work example, and run npm link gatsby-plugin-mdx. But that failed with something to the effect of Cannot find module 'webpack'. I think it has to do with missing peer dependencies. There must be a better way to do this…

[ascorbic]

@leafac The branch has been merged, so you should just need to check with the latest version of Gatsby. If you can do that, let us know if it fixes it for you.

[leafac]

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.

[danedavid]

The issue is with webpack mdx-loader not picking up remark parsers in gatsby-plugin-mdx. I have raised a PR https://github.com/gatsbyjs/gatsby/pull/24194, but not sure if the approach is right. But in that branch the issue is fixed.

[leafac]

What’s a practical way for me to test that branch?

[danedavid]

@leafac No easy way. Clone, build gatsby-plugin-mdx and link the project that reproduces the error 🤷

[leafac]

I’m sorry but I don’t have the time to test this right now, so I’ll just take @danedavid’s word that the issue is fixed.

[activatedgeek]

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.

[ehowey]

I am still running into this issue on recent versions of Gatsby.

To get it working I had to include gatsby-remark-katex, remark-math, and rehype-katex in the appropriate places in the mdx plugin config. Which is what I believe others have talked about above.

[danedavid]

I have a PR here which adds the remark parsers in mdx-loader. Fixed the issue in my testing. Could anyone please review it?

[leafac]

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

[ehowey]

@danedavid I will just second what @leafac already said. Sounds like you are missing the CSS. There are instructions on the plugin page for Gatsby.