Bug: MDX/Acorn error triggered by `text{` pattern in LaTeX arguments

[99JIK]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Problem Description:

When using certain LaTeX expressions involving the \frac command within $$...$$ (block math) or $ ... $ (inline math) delimiters in MDX files, a build error occurs: "Could not parse expression with acorn". The error details point to micromark-extension-mdx-expression as the source.

The LaTeX content itself is valid and renders correctly in other Markdown editors like Typora, but fails during the Docusaurus build process.

Reproducible demo

https://codesandbox.io/p/live/d53e7b8b-349c-4f5c-8d87-cde8b43f4887

Steps to reproduce

Steps to Reproduce / Specific Test Cases:

The issue was narrowed down using a minimal Docusaurus project containing only a single .md file with frontmatter and the test LaTeX expression.

1. Failing Case (Key Pattern):
The following LaTeX expression consistently causes the "Could not parse expression with acorn" error:

$$\frac{1}{a{{}}$$

The error points to the line containing this expression, specifically around the a{ part in the denominator.

2. Passing Cases (Slight Variations):
The following similar expressions pass successfully:

$$\frac{1}{{}}$$
$\frac{1}{{a}}$

3. Original More Complex Failing Case:
The issue was initially observed with more complex formulas like:

$$Attention(Q, K, V) = softmax(\frac{QK^T}{\sqrt{d_k}})V$$
$Attention(Q, K, V) = softmax(\frac{QK^T}{\sqrt{d_k}})V$

Further tests on the block version showed that simplifying this to $$Attention(Q, K, V) = \frac{QK^T}{\sqrt{d_k}}V$$ (removing softmax) still failed.

4. Passing Cases (Avoiding \frac or the problematic pattern):

• Simple inline math like $a_k = c^2 + b$ works fine.
• If the complex Attention formula is rewritten to avoid the \frac command (e.g., by using negative exponents like QK^T (\sqrt{d_k})^{-1} or QK^T d_k^{-1/2}), the "acorn" error disappears and the build succeeds:

$$Attention(Q, K, V) = \operatorname{softmax}\left(QK^T (\sqrt{d_k})^{-1}\right)V$$ 
// This PASSES
$$Attention(Q, K, V) = \operatorname{softmax}\left(QK^T d_k^{-1/2}\right)V$$
// This PASSES

Expected behavior

Deduced Cause / Hypothesis:
The "Could not parse expression with acorn" error appears to be triggered when certain LaTeX commands are used and one of their arguments starts with one or more plain text characters immediately followed by an opening LaTeX curly brace {. While this behavior was most consistently observed with the denominator of the \frac command, it is hypothesized that other LaTeX commands (e.g., \sqrt, custom commands, etc.) could similarly be misinterpreted as MDX/JavaScript expressions if their arguments follow a similar pattern.

The hypothesis is that micromark-extension-mdx-expression (the component that parses MDX {...} JavaScript expressions), or an interaction between remark-math, rehype-katex, and the MDX expression parser, incorrectly interprets this specific LaTeX pattern (text{...}) within a math block ($$...$$ or $ ... $) as an MDX/JavaScript expression. The core issue seems to be that the math delimiters ($$...$$) are not fully or correctly isolating the LaTeX content from the MDX expression parser under these specific circumstances. In other words, the structural characteristics of certain LaTeX commands might act as unintentional triggers during the MDX parsing process, leading to areas of pure LaTeX code being mistaken for JavaScript contexts.

Actual behavior

---
slug: first-blog-post
title: First Blog Post
authors: [slorber, yangshun]
tags: [hola, docusaurus]
---

$$\frac{1}{a{}}$$

 *  Executing task: CodeSandbox: dev 

✔ Client
  Compiled successfully in 1.44s

[WARNING] Docusaurus found blog posts without truncation markers:
- "blog/2019-05-28-first-blog-post.md"

We recommend using truncation markers (`<!-- truncate -->` or `{/* truncate */}`) in blog posts to create shorter previews on blog paginated lists.
Tip: turn this security off with the `onUntruncatedBlogPosts: 'ignore'` blog plugin option.
client (webpack 5.99.9) compiled successfully

✔ Client
  Compiled successfully in 331.62ms

client (webpack 5.99.9) compiled successfully
[WARNING] Docusaurus found blog posts without truncation markers:
- "blog/2019-05-28-first-blog-post.md"

We recommend using truncation markers (`<!-- truncate -->` or `{/* truncate */}`) in blog posts to create shorter previews on blog paginated lists.
Tip: turn this security off with the `onUntruncatedBlogPosts: 'ignore'` blog plugin option.

✖ Client
  Compiled with some errors in 383.39ms

Error: MDX compilation failed for file "/project/workspace/blog/2019-05-28-first-blog-post.md"
Cause: Could not parse expression with acorn
Details:
{
  "cause": {
    "pos": 120,
    "loc": {
      "line": 8,
      "column": 12
    }
  },
  "column": 13,
  "message": "Could not parse expression with acorn",
  "line": 8,
  "name": "8:13",
  "place": {
    "line": 8,
    "column": 13,
    "offset": 120
  },
  "reason": "Could not parse expression with acorn",
  "ruleId": "acorn",
  "source": "micromark-extension-mdx-expression",
  "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn"
}

--------------------------

Error: MDX compilation failed for file "/project/workspace/blog/2019-05-28-first-blog-post.md"
Cause: Could not parse expression with acorn
Details:
{
  "cause": {
    "pos": 120,
    "loc": {
      "line": 8,
      "column": 12
    }
  },
  "column": 13,
  "message": "Could not parse expression with acorn",
  "line": 8,
  "name": "8:13",
  "place": {
    "line": 8,
    "column": 13,
    "offset": 120
  },
  "reason": "Could not parse expression with acorn",
  "ruleId": "acorn",
  "source": "micromark-extension-mdx-expression",
  "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn"
}
client (webpack 5.99.9) compiled with 2 errors
<w> [webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/project/workspace/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[9].use[0]!/project/workspace/node_modules/@docusaurus/plugin-content-blog/lib/markdownLoader.js??ruleSet[1].rules[9].use[1]!/project/workspace/blog/2019-05-28-first-blog-post.md?truncated=true': No serializer registered for VFileMessage
<w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> Error -> VFileMessage
<w> [webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/project/workspace/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[9].use[0]!/project/workspace/node_modules/@docusaurus/plugin-content-blog/lib/markdownLoader.js??ruleSet[1].rules[9].use[1]!/project/workspace/blog/2019-05-28-first-blog-post.md': No serializer registered for VFileMessage
<w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> Error -> VFileMessage
<w> [webpack.cache.PackFileCacheStrategy] Serializing big strings (928kiB) impacts deserialization performance (consider using Buffer instead and decode when needed)
<w> [webpack.cache.PackFileCacheStrategy] Serializing big strings (132kiB) impacts deserialization performance (consider using Buffer instead and decode when needed)

Compiled with problems:
×
ERROR in ./blog/2019-05-28-first-blog-post.md?truncated=true
Module build failed (from ./node_modules/@docusaurus/mdx-loader/lib/index.js):
Error: MDX compilation failed for file "/project/workspace/blog/2019-05-28-first-blog-post.md"
Cause: Could not parse expression with acorn
Details:
{
  "cause": {
    "pos": 120,
    "loc": {
      "line": 8,
      "column": 12
    }
  },
  "column": 13,
  "message": "Could not parse expression with acorn",
  "line": 8,
  "name": "8:13",
  "place": {
    "line": 8,
    "column": 13,
    "offset": 120
  },
  "reason": "Could not parse expression with acorn",
  "ruleId": "acorn",
  "source": "micromark-extension-mdx-expression",
  "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn"
}

    at compileToJSX (/project/workspace/node_modules/@docusaurus/mdx-loader/lib/utils.js:93:15)
    at async loadMDX (/project/workspace/node_modules/@docusaurus/mdx-loader/lib/loader.js:22:20)
    at async Object.mdxLoader (/project/workspace/node_modules/@docusaurus/mdx-loader/lib/loader.js:157:24)
ERROR in ./blog/2019-05-28-first-blog-post.md
Module build failed (from ./node_modules/@docusaurus/mdx-loader/lib/index.js):
Error: MDX compilation failed for file "/project/workspace/blog/2019-05-28-first-blog-post.md"
Cause: Could not parse expression with acorn
Details:
{
  "cause": {
    "pos": 120,
    "loc": {
      "line": 8,
      "column": 12
    }
  },
  "column": 13,
  "message": "Could not parse expression with acorn",
  "line": 8,
  "name": "8:13",
  "place": {
    "line": 8,
    "column": 13,
    "offset": 120
  },
  "reason": "Could not parse expression with acorn",
  "ruleId": "acorn",
  "source": "micromark-extension-mdx-expression",
  "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn"
}

    at compileToJSX (/project/workspace/node_modules/@docusaurus/mdx-loader/lib/utils.js:93:15)
    at async loadMDX (/project/workspace/node_modules/@docusaurus/mdx-loader/lib/loader.js:22:20)
    at async Object.mdxLoader (/project/workspace/node_modules/@docusaurus/mdx-loader/lib/loader.js:157:24)

Your environment

• Public source code: https://github.com/99JIK/Today_I_Learned
• Public site URL: https://til.jungin.kim
• Docusaurus version used: 3.7.0, 3.8.0
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 136.0.7103.114, Node.js 18.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 11, Ubuntu 24.04.2 LTS

Self-service

• I'd be willing to fix this bug myself.

P.S. Lastly, please excuse any lack of clarity or awkward phrasing due to my limited English proficiency. I've tried my best to describe the issue accurately.

[slorber]

Your repro is marked as private, I can't access that link.

You have a missing closing } in your expression $$\frac{1}{a{{}}$$

It works if you close it

We use KaTeX, so make sure to check your expression in KaTeX first. We won't support any expression it doesn't support.

Your "more complex formulas" work fine to me:

$$Attention(Q, K, V) = softmax(\frac{QK^T}{\sqrt{d_k}})V$$
$Attention(Q, K, V) = softmax(\frac{QK^T}{\sqrt{d_k}})V$

[sbozzie]

I am facing this issue with the following formula:

$$ T_{LCA,Q_n}\equiv\frac{200|P_{b,Q_{n}}|}{rP_{rated}} $$

T_{LCA,Q_n}\equiv\frac{200|P_{b,Q_{n}}|}{rP_{rated}}

[slorber]

@sbozzie FYI we now recommend math code blocks instead of $$ syntax for this reason:

https://docusaurus.io/docs/markdown-features/math-equations#blocks