Broken asset links when using cleanUrl setting

[eimerreis]

🐛 Bug Report

When using the cleanUrl: true setting, docusaurus generates new sub folders for each site. For example, if you want clean url /docs/Connectivity, what docusaurus generates is a sub folder called Connectivity with an index.html file in it instead of the original Connectivity.html.

I really like the idea of this, but when the index.html within a cleanUrl subfolder references an image from the docs/assets folder, the link is broken because it's still relative to the original docs/ folder.

To Reproduce

1. Set cleanUrl to true in siteConfig.js
2. Reference an image from the assets folder within your markdown file
3. Browse to the clean url, e.g. docs/Contributing, instead of docs/Contributing.html
4. Image in clean URL is broken, in .html document image will work.

Expected behavior

When setting cleanUrl to true, docusaurus generates correct asset links to parent directory, where asset directory is located.

Actual Behavior

Image is broken due to link still being relative to parent directory instead of being relative to the directory created for clean url

[endiliey]

1.We actually produce connectivity.html and connectivity/index.html when cleanUrl is true.

2. How did you reference the image ?

Example:

![test](/docs/assets/activeMachine.png)

Our documentation recommend on using absolute url path instead of relative path.

[eimerreis]

@endiliey thanks for your fast reply!

you're right, we're actually not using absolute paths. I'll figure out if we can change this in our existing documentation.

Do you see this as an issue for larger projects? I'm thinking about big projects with existing markdown structures using relative paths, trying to use Docusaurus.

[endiliey]

@eimerreis

Actually this relative path case will happen on i18n and/or versioned website as well.

1. i18n website has urls like /docs/en/, /docs/ja.
2. versioned website has urls like /docs/next/.
3. i18n & versioned website has urls like /docs/en/next

Thanks for reporting this. We are most likely going for a rewrite in v2 so I’ll add it to the long term nice-to-have list for now.
Meanwhile, I recommend using absolute url to ensure that you won't get this problem.

[eimerreis]

@endiliey

Nice to hear! 😊

After thinking about this for a while, this would be a great improvement for the general UX / DX of docusaurus, since users would not have to adpot their existing markdown in any way to work with docusaurus, providing i18n and versionning out of the box.

This would make Doucsaurus stand out even more than it already does from other tools 👍

[jpwain]

Have any workarounds been found for this issue? I started using absolute URLs so my images render on the published website, but they don't show up for local builds as expected.

[endiliey]

Marking this as wontfix in v1. The recommended way is to use absolute URL.

This should be out of the box in v2 (I think)

[zhyinghao]

Have any workarounds been found for this issue? I started using absolute URLs so my images render on the published website, but they don't show up for local builds as expected.

@jpwain

I am using this as a workaround:

1. Use relative paths in markdown so images show up in the local markdown editor without setting something like an image root path
2. Disable cleanUrl so the relative paths will break after markdown files are converted to html

Absolute paths are great if the markdown files are for websites only. But unfortunately, I am also running the same markdown files through DITA Open Toolkit to generate PDFs, and DITA OT won't recognize the absolute paths.