Docusaurus: Support prepending of base url in markdown image paths

[aeneasr]

🚀 Feature

I want to display images without using JSX in my Markdown code

![my image](/static/img/...)

and have Docusaurus modify the image src using the project's baseUrl.

Have you read the [Contributing Guidelines on issues]

Yes

Motivation & Pitch

Currently, it's recommended to link to an image using:

import useBaseUrl from '@docusaurus/useBaseUrl'

<img alt="ORY Oathkeeper with Prometheus and Grafana" src={useBaseUrl('img/docs/grafana.png')} />

This has several disadvantages. First it doesn't work with native markdown and thus looks confusing when browsing the docs on e.g. GitHub (both in preview and raw view!):

Second it's hard to understand for people who don't know Docusaurus. None of our docs contributors has figured out how to use this correctly. This means that the time to merge for docs changes goes up and frustrates both maintainers as well as contributors.

Third it breaks previews. Assuming that - as it's documented - the import is always the first element, we get previews in Slack

and even the HTML meta tags which is a SEO-killer:

Please consider adding this functionality to Docusaurus. I'd be happy to help!

[yangshun]

To get around this, you can override the description field in the front matter of your markdown docs. @lex111 has also worked on stripping import statements from the docs so this problem might not exist now. But adding support for prepending markdown paths with the baseUrl would be useful, possibly via a new syntax.

[jknoxville]

Hey @yangshun I'd be happy to work on this, but since the syntax of markdown is already pretty well defined, it would be a shame to have to use a different one.

Would it be out of the question to change the default to always prepend the baseUrl? I imagine it's much more common than wanting to link to "outside" of the docusaurus site. You could still do that by using tags like the example above if you want to.

Or if not that, maybe an option you can set (possibly in docusaurus.config.js) to toggle this behaviour?

[aeneasr]

Linking to external images would work regardless of the automatic pre-use of useBaseUrl: https://my-domain/my-image.png. I don't think there's actually a use case for not base-url'ing the images given of how static files are loaded. I haven't used a single image reference without this hack (it is a hack because it's not native markdown) yet, and that includes hundred pages of docs :)

[slorber]

Hey, this issue is already solved imho, you can use relative image paths (and colocate the image to its doc too, if needed):
https://v2.docusaurus.io/docs/markdown-features/#image-assets

It uses webpack file-loader under the hook, which also provides nice benefits: we can now detect bad image paths at compile time, + add a hash to the image URL so that it can be cashed more aggressively.

I don't like useBaseUrl either, and would like to deprecate it.

Can we close this PR?

[jknoxville]

Ah ok, thanks, I'll give that a go :)

I was trying to use relative images today but didn't realise you had to import them, so the build would fail unless I prepended them with filepath://.
It's not directly related but that error message could use some improvement. It just said something like "can't resolve module url-loader". I can imagine a lot of people hitting that.

[slorber]

hmmm, this is surprising because url loader is a core dependency, and is indeed a required dep for this feature to work.

Are you using something like yarn 2, pnp or something else? Did do yarn install? Can you run yarn why url-loader?

It may be because one of our package does not expose directly it as a direct dependency. Was precisely working on a bugfix of this part, we'll see in next release if it works better for you.

[aeneasr]

Yup, this is apparently solved indeed. We can close it IMO :)

[slorber]

@jknoxville is it working for you? How did you find about filepath:// by reading the source code?

[jknoxville]

@slorber sorry for the delay getting back to you. This is the build error I get if I use a markdown image without importing that particular image with both the following syntax:

![](./poisson.png)
![](poisson.png)

(where poisson.png is a file in the same dir as the markdown file referring to it)

../docs/overview/quick_start/quick_start.md
Module not found: Can't resolve 'url-loader' in '/data/sandcastle/boxes/fbsource/fbcode/beanmachine/docs/overview/quick_start'
Client bundle compiled with errors therefore further build is impossible.
../docs/overview/quick_start/quick_start.md
Module not found: Error: Can't resolve 'url-loader' in '/data/sandcastle/boxes/fbsource/fbcode/beanmachine/docs/overview/quick_start'
 @ ../docs/overview/quick_start/quick_start.md 1:5502-5610
 @ ./.docusaurus/registry.js
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/@docusaurus/core/lib/client/clientEntry.js
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

yarn why url-loader

Using Yarn from /data/sandcastle/boxes/fbsource/xplat/third-party/yarn/yarn
yarn why v1.17.0-20190429.1820
[1/4] Why do we have the module "url-loader"...?
[2/4] Initialising dependency graph...
[3/4] Finding dependency...
[4/4] Calculating file sizes...
=> Found "[email protected]"
info Reasons this module exists
   - "@docusaurus#core" depends on it
   - Hoisted from "@docusaurus#core#url-loader"
   - Hoisted from "@docusaurus#preset-classic#@docusaurus#plugin-content-blog#@docusaurus#mdx-loader#url-loader"
info Disk size without dependencies: "492KB"
info Disk size with unique dependencies: "596KB"
info Disk size with transitive dependencies: "3.02MB"
info Number of shared dependencies: 11
Done in 1.02s.

I'm using yarn 1.17.0, the one that runs as standard at facebook.

I think the filepath:/// thing was a red herring, I found it in an issue by googling the error message, and thought it might be the new required syntax so gave it a try.

---

So speaking for myself, I still can't get any images to work using the markdown syntax.
Maybe I'm doing something wrong, but as far as I can tell I'm following the docs.

Tried on versions 58 and 61.

To clarify, I'd be happy with the restriction to only use absolute paths instead, but they don't currently get the baseUrl prepended.

[slorber]

This is weird
I have no idea what's going on but it's supposed to work.

These features are new so don't stay on alpha 58.
Are you sure you have all your deps on Docusaurus alpha 61?
May be worth to inspect your lockfile, or try regenerating it.

What gives yarn why @docusaurus/core ?
What gives yarn why @docusaurus/mdx-loader ?

Can you create a small repro?

Maybe try to remove the .docusaurus folder?
This one too website/node_modules/.cache/cache-loader

[jknoxville]

Thanks for the help @slorber

I regenerated the yarn.lock, and verified that it only contains v61 of any docusaurus packages, still the same thing.

However, I tried out using relative markdown images on the docusaurus website itself, and it works, so I can agree with you that relative images do in fact work and this issue can be closed :) there's just clearly something wrong with this other docusaurus installation, but as far as I know thats unrelated to this issue.

[slorber]

Great to know :)

This is weird that it doesn't work on your website. Unfortunately without a repro it will be hard to troubleshot.

[slorber]

@jknoxville I think @anshulrgoyal found out why the url loader does not work in your case, because the docs are outside of the website, and it does not resolve against parent/website/node_modules but against parent/node_modules.

Adding URL loader in the parent is likely to solve this issue, but we'll also add resolution to website/node_modules, as it's likely to be useful for those migrating from docusaurus v1 and keeping docs in place.

I've seen this on Flipper: https://github.com/facebook/flipper/blob/master/website/docusaurus.config.js#L118

Did you migrate from v1 and decided to keep the docs in place instead of moving them?

[jknoxville]

Did you migrate from v1 and decided to keep the docs in place instead of moving them?

Yes exactly, I didn't see a reason to move them, but can do if it's necessary. I'd prefer that than having to turn the parent into a JS package.

[slorber]

No it should be supported, we don't want to force users to move folders as it seems it can messup a bit the git history 🤪 we are currently experiencing that in RN website migration