Docusaurus SSG warnings - troubleshooting

[slorber]

Starting with Docusaurus v3.6 and Docusaurus Faster, our new HTML minifier can emit diagnostic errors, that we now log to the console as warnings by default.

These warnings can be a bit verbose/annoying, and we made it possible to disable them with DOCUSAURUS_IGNORE_SSG_WARNINGS=true.

For now, only our HTML minifier emits those warnings, and its messages aren't always super clear (and it provides an input HTML char number, not a line number)

You can ignore these warnings, and your site will probably keep working just fine, even if it contains invalid HTML markup. But it's preferable to ensure your site has a valid HTML markup.

This issue is to help you troubleshoot these issues.

How to troubleshoot

Most of the time, the errors are related to invalid HTML markup such as:

• <li> element inside <p>
• <a> inside <a>
• <p> inside <p>
• other similar cases

These issues can often happen due to how MDX compiles your Markdown to JSX, in particular when using JSX inside your MDX documents. A regular Markdown file with no JSX tag shouldn't have any problem. Note that any other React component on your site can produce invalid markup.

The best is to pass your content to the MDX Playground to see how it compiles it.

You can also remove parts of your MDX documents (or React components) until the warning disappears to find the problematic part.

Example 1

This might surprise you but the following will produce invalid HTML:

<p>
  content
</p>

This gets compiled by MDX as:

export default function MDXComponent() {
  return (
    <p>
      <p>content</p>
    </p>
  );
}

As you can see, there's a duplicate <p> tag, which is invalid HTML!

The solution in this case is:

<p>content</p>

or

<p>
  <>content</>
</p>

Example 2

Similarly, with GitHub Flavored Markdown and auto-linking of URLs and emails, the following will lead to invalid HTML:

<a href="https://example.com">
  https://example.com"
</a>

MDX will compile it as:

export default function MDXComponent() {
  return (
    <a href="https://example.com">
      <p>
        <a href="https://example.com">https://example.com</a>
      </p>
    </a>
  );
}

As you can see, there are duplicate <a> tags, , which is invalid HTML!

The solution in this case is:

https://example.com

or

<a href="https://example.com">
  {'https://example.com'}
</a>

---

Let us help you

We created this issue to help you troubleshoot these warnings.

But you have to let us help you!

We won't be able to help if you only share a raw error message.

We kindly ask you to share a minimal repro created with https://docusaurus.new or yarn create docusaurus. Support requests not providing enough information will be ignored.

Before doing so, please apply the method above: use the MDX playground and remove content until the warning disappears to identify the location.

[o-l-a-v]

Would be great if the links generated in the output of this check actually could be used to open the file in question in VSCode, by CTRL + mouse left click in the terminal output. Also on Windows shich uses backslash \.

[slorber]

@o-l-a-v how to do so? The HTML minifier doesn't know what file produces the error, it only knows what HTML file / pathname has invalid HTML markup. It might be coming from an MDX file, a React file, a partial or even a third-party lib on npm.

At best, we could add a http://localhost:3000 link, but it's not ideal either because we don't know on which host/port the user will run the static deployment.

---

Note: null character errors are likely a React 18 bug, not something you can fix. Those errors are supposed to be ignored automatically. See:

• Output HTML contains NULL chracters in at least CJK languages #9985

docusaurus/packages/docusaurus/src/ssg/ssg.ts

Line 120 in 5a883b4

'Unexpected null character',

[o-l-a-v]

Ah, okey.

(I'm no JS dev so I have little idea how this works behind the scenes. 😄)

[mike-solomon]

👋 heyo - I wanted to look into an issue, so I followed the instructions and went to https://docusaurus.io/docs/playground and clicked on the StackBlitz link. However, when I went there (for both JavaScript and TypeScript) – I got an error installing dependencies:

I then tried going to the CodeSandbox link - but I couldn't figure out how to actually edit any of the files. Whenever I clicked on them all I would see is a preview and I couldn't type or enter text anywhere:

Any idea what might be going wrong here? Should I make a separate issue for this?

To add some more details: I'm on a M2 Mac running Sequoia 15.1 using the Arc browser running version 1.63.1.

I tried going to CodeSandbox in Firefox as well to test - and I also couldn't edit any files. For StackBlitz, in FireFox, it spun on installing dependencies for a few minutes and didn't seem to progress.

[mike-solomon]

I've created a new docusaurus site that can be found here: https://github.com/mike-solomon/docusaurus-testing/blob/main/website/docs/intro.md?plain=1

In that file, I'm getting this error:

- [HTML minifier diagnostic - error] No "p" element in scope but a "p" end tag seen - {"primary_spans":[{"end":10397,"start":10393}],"span_labels":[]}

If you remove this whole <figure> chunk the error no longer appears:

<figure>
  ![](./assets/LST-comparison.png)
  <figcaption>_LST comparison_</figcaption>
</figure>

Any suggestions on how to handle figures differently? I originally went with <figure> so I could use CSS to position it in a way I want - and then have the caption tied to the figure.

Thanks!

[mike-solomon]

For anyone else who was a bit confused by how to disable these warnings (I originally tried passing it in as a flag rather than an environment variable):

If you're building locally you can:

DOCUSAURUS_IGNORE_SSG_WARNINGS=true yarn build

# OR

export DOCUSAURUS_IGNORE_SSG_WARNINGS=true
yarn build

If you're deploying to GitHub pages:

- name: Build website
    run: yarn build
    env:
      DOCUSAURUS_IGNORE_SSG_WARNINGS: true

[slorber]

Thanks for clarifying.

Note the terminal env variable declaration can vary. It's also possible to add a package.json script including an env varialb that works for all systems with cross-env: https://github.com/kentcdodds/cross-env

"build": "cross-env DOCUSAURUS_IGNORE_SSG_WARNINGS=true docusaurus build"