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]

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]

@slorber No pressure as I know you're super busy - but just wanted to check in and see if this was enough information for this question. Unsure if this was skipped because I didn't provide enough information or if you accidentally skipped over it or if you just haven't had time to look at it (no worries whatever the case).

[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"

[ltribolet]

I noticed using:

<details>
<summary>Collapsed content</summary>
<p>

This is an example of collapsed code

```js
console.log("hello")
```

</p>
</details>

Will produce this warning:

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

What would be the workaround? I tried removing the <p></p> but I suspect new lines and probably the code block are producing some HTML elements that you outlined in the first message. However with codeblock I don't think adding <></> will make it work.

(By the way I tried to use Codesandbox but couldn't find a way to share my example, I don't know how to use it, when sharing it shows outdated code)

[slorber]

@ltribolet you have to use the MDX playground to figure out the solution and get it to render the markup you want.

https://mdxjs.com/playground/

I tried removing the <p></p> but I suspect new lines and probably the code block are producing some HTML elements that you outlined in the first message. However with codeblock I don't think adding <></> will make it work.

Isn't this what you want?

What HTML elements are you referring to? What is the problem you think will "not work" with code blocks. What does it mean for HTML to not work? This is too vague for me to understand, please be more concrete.

What is the expected HTML/React code you want, and what is the actual, problematic HTML/React you get?

Do you even know exactly what you want? I can only help you if you have clear expectations. Give me the exact markup you want, and I'll tell you how to obtain it.

[ltribolet]

@ltribolet you have to use the MDX playground to figure out the solution and get it to render the markup you want.

https://mdxjs.com/playground/

I used it but because it was rendering my example without warning or error, I didn't know where to go from there without more detailed instructions.

Not sure what to make of this as I am not used to look into generated javascript like this, why would this produce the warning?

Isn't this what you want?

This is still producing the warning message, this is what I badly explained.

What is the expected HTML/React code you want, and what is the actual, problematic HTML/React you get?

Do you even know exactly what you want? I can only help you if you have clear expectations. Give me the exact markup you want, and I'll tell you how to obtain it.

Well most of my contributors don't know MDX, they know Markdown (and Github Markdown flavour for that matter), so if we have to adapt it or write it like this:

<details>
<summary>Collapsed content</summary>
<>This is an example of collapsed code</>

```js
console.log("hello")
```
</details>

I think it's manageable for simple cases, for longer and more complex cases it's gonna be really verbose. However if this is the new direction, to get faster builds we compromise the readability for the writer, I'm ok then just silencing those warnings.

I was just trying to avoid <></> as much as possible, as this was working without warnings before.

[slorber]

This is still producing the warning message, this is what I badly explained.

I tried the suggested MDX and it doesn't produce the warning message. If that's the case, double-check your setup and provide a bug repro.

<details>
  <summary>Collapsed content</summary>

    This is an example of collapsed code

    ```js
    console.log("hello")
    ```

</details>

Well most of my contributors don't know MDX, they know Markdown (and Github Markdown flavour for that matter)

We have a CommonMark mode if you don't know/like MDX:

https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark

so if we have to adapt it or write it like this:

<details>
<summary>Collapsed content</summary>
<>This is an example of collapsed code</>

```js
console.log("hello")

```

I think it's manageable for simple cases, for longer and more complex cases it's gonna be really verbose.

I'm not recommending the above. As explained my code snipped above without fragments should work fine, you can simply remove the <p> tags.

However if this is the new direction, to get faster builds we compromise the readability for the writer, I'm ok then just silencing those warnings.

This is not the "new direction", it's just that you had malformed HTML in the first place, and then now our new HTML minifier (that you can opt-out individually) tells you about it. The HTML markup problem has always been there.

I was just trying to avoid <></> as much as possible, as this was working without warnings before.

Your initial snippet had problems in the first place (duplicate <p> tags in the final static HTML file), it's just that you weren't aware of that problem. Now you are, and have the opportunity to fix it, or ignore it. We don't always recommend using <> like you seem to think.

[ltribolet]

This is still producing the warning message, this is what I badly explained.

I tried the suggested MDX and it doesn't produce the warning message. If that's the case, double-check your setup and provide a bug repro.

<details>
  <summary>Collapsed content</summary>

    This is an example of collapsed code

    ```js
    console.log("hello")
    ```

</details>

I tried again and I understand Where I made a mistake, this will produce a warning:

<details>
<summary>Collapsed content</summary>
This is an example of collapsed code

```js
console.log("hello");
```

</details>

(example here, managed to get the share working on Sandboxes)

While this won't:

<details>
<summary>Collapsed content</summary>

This is an example of collapsed code

```js
console.log("hello");
```

</details>

This is not the "new direction", it's just that you had malformed HTML in the first place, and then now our new HTML minifier (that you can opt-out individually) tells you about it. The HTML markup problem has always been there.

Your initial snippet had problems in the first place (duplicate <p> tags in the final static HTML file), it's just that you weren't aware of that problem. Now you are, and have the opportunity to fix it, or ignore it. We don't always recommend using <> like you seem to think.

Makes sense, thanks for taking the time, I better understand what's going on.