Inconsistency in how image paths are handled between markdown links and img hrefs

[dwmkerr]

(I'd be happy to work on this issue if someone can point me in the right direction to get started)

It could be argued this is not a bug, but it is certainly unintuitive behaviour that makes things a little harder to work with.

Consider a folder in docs that contains a markdown file and an image (this is a pattern that I think could be pretty comon - each docs page contains its own folder of images, i.e. co-locating images with their associated document, if they are specific to the document, rather than shared across the site):

docs
-> folder1
-> folder1/index.md
-> folder1/images/image.png

The following markdown snippet will correctly render the image:

![Alt Text](./images/image.png)

As this works. GitHub also correctly renders this in pull requests etc.

I think the user would expect that the following would also work:

<img alt="Alt Text" src="./images/image.png" width="480px" />

This form might be used if you want to control the style/width of an image. The snippet above also renders correctly in a GitHub markdown preview in a code change.

However, instead we have to use this form:

<img alt="Alt Text" src={require('./images/image.png').default} width="480px" />

This works - however it is unintuitive that this form has to be used given that the pure markdown version works with relative paths properly. It also means that typical markdown previewing tools (such as GitHub's own markdown renderer) fail to render the images. This just makes the process of working with images that are co-located with documents a bit more painful.

I love the tool - I'm migrating Effective Shell to Docusaurus at the moment - one of the reasons I prefer it to Hugo is that I don't have to use weird platform specific features (like relref in Hugo) - I can just use plain old markdown links. But this img behaviour is a little odd. I understand it's a low priority issue with a simple workaround, but feels like the entire tool would be a little more user friendly (especially for complex folder structures like mine) if it was possible to use plain old relative paths in img tags.

An example of this inconsistency (which also shows how GitHub fails to render the img tags properly) is at: https://github.com/dwmkerr/effective-shell/blob/main/effective-shell/docs/01-transitioning-to-the-shell/01-getting-started/index.md

Please see the sandbox at: https://codesandbox.io/s/serene-butterfly-fz6tk?file=/docs/image-issue/image-issue.md

Steps to reproduce

Please see above, or the code at:

• https://github.com/dwmkerr/effective-shell/blob/main/effective-shell/docs/01-transitioning-to-the-shell/01-getting-started/index.md
• https://codesandbox.io/s/serene-butterfly-fz6tk?file=/docs/image-issue/image-issue.md

Expected behavior

Image tags would be able to reference images using relative paths without any special treatment.

Actual behavior

Image tags that reference images in relative paths require us to use require - this fails to preview in many common markdown renderers - such as GitHub's own renderer, meaning we are more likely to make mistakes when using these paths.

Your environment

• Public source code: https://github.com/dwmkerr/effective-shell - docusaurus version is in the subfolder effective-shell
• Public site URL: https://effective-shell.com/effective-shell
• Docusaurus version used: 2.0.0-beta.14
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node v14.15.1, Chrome Version 97.0.4692.71 (Official Build) (x86_64)
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS Catalina 10.15.7 (19H1615)

Reproducible demo

https://github.com/dwmkerr/effective-shell/tree/main/effective-shell

This was referenced in bug #6403 that was closed but I believe it is still worthy of discussion as it affects the usability / learning curve of the framework.

[Josh-Cena]

I find it quite intractable to explain😅 Let me try again.

Markdown is the realm we can control, because we host a Markdown compiler ourselves. Therefore, we can do our best to infer what you want if you write Markdown, even if the corresponding JSX isn't valid OOTB. Therefore, if you write ![Alt Text](./images/image.png), when we parse the Markdown, we understand that you want the corresponding image to be built as well, hence we convert it to a require() call for you. Otherwise, you would end up with a nonexistent image at runtime, because Webpack doesn't include assets that aren't required.

JSX is the realm we can't control, because we don't ship our own JSX runtime. We can do some basic transformation, but we figured that too much transformation would be more surprising than helpful to users familiar with React. When you write <img alt="Alt Text" src="./images/image.png" width="480px" />, it isn't processed by us, it isn't processed by MDX, but it is directly sent down as React code and gets eventually rendered to the DOM by React as-is. src="./images/image.png" itself is a valid thing to write, because consider this: your site is ultimately compiled to HTML and served statically. You may magically inject an images/image.png file post-build, and hence make the source both correct and functional. Who knows? We don't, and we don't make assumptions about JSX that's syntactically valid.

I think what led to your confusion is that you have that sense of Markdown -> HTML mapping already burnt into your understanding of Markdown. Get rid of that. Markdown doesn't strictly correlate with HTML—it's just declarative markup. There's no promise that ![Alt Text](./images/image.png) will always be compiled to <img src="./images/image.png" alt="Alt Text" />. ![]() only tells the build tool that "I want a image here with path ./images/image.png", and whether you actually end up with the exact same src attribute is not promised. No-one even promised that ![]() is equivalent to an img tag—I can produce an svg as well, or a figure encapsulating an img. Compare that to JSX, however—JSX is much more imperative. When you write <img src="./images/image.png" alt="Alt Text" />, you mean that, because JSX is always strictly correlated with HTML markup.

[CMCDragonkai]

const visit = require('unist-util-visit');

const plugin = (options) => {
  const transformer = async (ast) => {
    let number = 1;
    visit(ast, 'heading', (node) => {
      if (node.depth === 2 && node.children.length > 0) {
        node.children.unshift({
          type: 'text',
          value: `Section ${number}. `,
        });
        number++;
      }
    });
  };
  return transformer;
};

module.exports = plugin;

The docs for building a custom remark plugin seems a bit out of date. Installing unist-util-visit only allows ES6 imports, and not require. I did decided to downgrade to the version of unist-util-visit already installed afterwards as 2.0.3.

But then I got type check failures:

[Josh-Cena]

I'll admit that doc was written pretty lately and the information that you need to downgrade unist-util-visit is only omitted because of laziness :)

RE: type-checking failure. It's quite common when developing Remark plugins (I've felt this myself). You would need to add an explicit annotation like this:

docusaurus/packages/docusaurus-mdx-loader/src/remark/headings/index.ts

Line 19 in 9150c7a

visit(root, 'heading', (headingNode: Heading) => {

In JSDoc, I believe this is done with a /** @type **/.

[CMCDragonkai]

I see, I just took out the type check with // @ts-check.

I'm not really familiar with TS type annotations, I didn't even know they existed. It's quite difficult to know what times to import and from where, so in the future I reckon the docusaurus.config.js should just support docusaurus.config.ts.

[CMCDragonkai]

Ok I got something working:

const remarkImageSrcWithBase = (options) => {
  return async (ast) => {
    visit(ast, 'jsx', (node) => {
      const matches = node.value.match(/^(<img\s.*?src=")\s*(\/.*)$/);
      if (matches != null) {
        node.value = `${matches[1]}/docs${matches[2]}`;
      }
    });
  };
};

And I put it into remarkPlugins.

[CMCDragonkai]

I got 2 versions of this now:

/**
 * Docusaurus does not process JSX `<img src ="...">` URLs
 * This plugin rewrites the URLs to be relative to `baseUrl`
 * Markdown links `[]()`, images `![](/image)` and anchor `<a href="...">`
 * are already automatically processed
 */
const remarkImageSrcWithBase = (options) => {
  return (ast) => {
    visit(ast, 'jsx', (node) => {
      const matches = node.value.match(/^(<img\s.*?src="\s*)\/(.*)$/);
      if (matches != null) {
        node.value = `${matches[1]}${baseUrl}${matches[2]}`;
      }
    });
  };
};

/**
 * Docusaurus does not process JSX `<img src ="...">` URLs
 * This plugin rewrites the src attribute to `src={require("...").default}`
 * Markdown links `[]()`, images `![](/image)` and anchor `<a href="...">`
 * are already automatically processed
 */
const remarkImageSrcWithRequire = (options) => {
  return (ast) => {
    visit(ast, 'jsx', (node) => {
      const matches = node.value.match(/^(<img\s.*?src=)"(\s*\/.*?)"(.*)$/);
      if (matches != null) {
        node.value = `${matches[1]}{require("${matches[2]}").default}${matches[3]}`;
      }
    });
  };
};

I think the second one is better as that always uses the require() as markdown images would normally do.

[CMCDragonkai]

Also I want to point out that this change isn't required for <a href="...">. It appears this becomes relative to the baseUrl, even though <img src=""> isn't relative to baseUrl. What was the reason to process markdown links []() and <a href> links and ![]() markdown images, but not <img src>?

[Josh-Cena]

<a> tags is always transformed to <Link> tags through a runtime MDXProvider map—this is dynamic. We can't do that for <img>, because it must be statically transformed during build-time so that Webpack can analyze the require usage.