Disable Error Overlay on Markdown image not found

[kieronlanning]

Hi, I'm importing an old wiki into Docusaurus and I've a long way to go.

As part of the initial prep, I wanted to view the site and all it's markdown as it currently stands.

But the site fails with missing/ broken images referenced in the Markdown. While I'll care about that in the future - during this stage, I'd like to disable that error/ warning and allow the site to continue to build/ load/ render.

I had assumed that by setting markdown.format: 'detect' it would use CommonMark rather than the MDX parser (as-per the docs), but as you can see the MDX process is the one throwing up errors.

❓ Can the overlay be disabled?

[slorber]

We can't disable the error overlay, however it seems we have 3 users requesting to disable these broken image error messages on the same week, so we'll likely implement something soon.

Related issue: #11219

I had assumed that by setting markdown.format: 'detect' it would use CommonMark rather than the MDX parser (as-per the docs), but as you can see the MDX process is the one throwing up errors.

The CommonMark mode means it will parse standard Markdown syntax, but it doesn't mean that it will entirely disable our markdown processing pipeline under the hood. Even if your doc is parsed in a less strict way and supports regular Markdown syntax, it's still compiled by MDX and outputs a React component under the hood, and we still use our regular pipeline to check images and links.

[kieronlanning]

Perfect, thanks! I'll mark this as the Answer for now in that case, assuming the feature arrives at some point in the future! Thankyou!

[kieronlanning]

@slorber Out of a matter of interest, and project planning... so you have a timeline for adding this feature?

[slorber]

I'll try to start working on it soon but it's a new feature and will wait for v3.9, probably the last v3.x release for which I'd like to add a few more future flags, so even if we merge it soon, I'm not sure it will be released soon.

The implementation will be a remark plugin, so technically you can already implement this behavior in userland yourself.

Most likely we'll handle this behavior here: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts#L127

You could add a remark plugin that replaces images that do not exist with a 404.png or something, so that our own remark plugin doesn't error.

---

Note that we don't check if images exist when you prefix the image path with pathname:// protocol, in which case we just output in the HTML the rest (pathname://<rest>) without any processing, so you could also write a remark plugin that add that pathname protocol to all your markdown images.

Here's a pseudo-implementation you can try adding to the beforeDefaultRemarkPlugins plugin options:

function remarkPlugin() {
  return async (root, vfile) => {
    const {visit} = await import('unist-util-visit');
    visit(root, 'image', (node) => {
      node.url = `pathname://` + node.url;
    });
  };
};

TLDR: you can pre-process Markdown files so that we see a different Markdown and to not error

[kieronlanning]

@slorber That's what I was thinking - already had a proof of concept, but as part of my mass import/ convert/ mangle/ merge process.

Thanks!