Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Linking to images in docs is broken when docsUrl configuration is used #1203

Closed
amimas opened this issue Jan 24, 2019 · 6 comments
Closed

Linking to images in docs is broken when docsUrl configuration is used #1203

amimas opened this issue Jan 24, 2019 · 6 comments

Comments

@amimas
Copy link

amimas commented Jan 24, 2019

🐛 Bug Report

In my siteConfig.js, I configured docsUrl: '' so that when docs are served, I don't have the .../docs/... in the url. This seems to break the image links/rendering.

Have you read the Contributing Guidelines on issues?

yes

To Reproduce

(Write your steps here:)

  1. Add docsUrl: '' to siteConfig.js
  2. I then followed the following instruction and created an docs/assets directory with my images.
Linking to Images and Other Assets
Static assets can be linked to in the same way that documents are, using relative URLs. Static assets used in documents and blogs should go into docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

Example:

![alt-text](assets/doc-image.png)

The site does not render the images in the docs. At first, I thought it's because I'm referring to the assets from the markdown files that are in subdirectory. Trying to manipulate the url to images in markdown files didn't help. Then I tried it from the markdown files that are directly under the docs directory. Images still would not render.

Removed the docsUrl: '' config from the siteConfig.js and now the image links are working even from markdown files that are in subdirectories of docs.

Expected behavior

Images are rendered even when docsUrl: '' configuration is used.

Actual Behavior

Images do not rendered.

Reproducible Demo

Sorry, I am currently dealing with a private repository. That's why I cannot share a reproducible demo at the moment. If the above information is not clear, please advise and I'll try to create a separate repo with this bug.

@JoelMarcey
Copy link
Contributor

@yangshun Have you seen this before?

@marvinchin
Copy link
Contributor

marvinchin commented Jan 26, 2019

This seems to be related to #1177. I've tried to reproduce the problem and I think I may found the issue.

In development environment (i.e. running docusaurus start), the server seems to be serving docs assets at the url specified by the docsUrl attribute specified in siteConfig.js, while the generated asset links are still referencing /docs/assets/ASSET_NAME. The images are not found at this location and are hence not shown.

When building for production, however, the generated assets are still placed in the docs folder instead of the url specified by the docsUrl attribute. Thus, the asset links to /docs/assets/ASSET_NAME now finds the requested asset and is able to load and display the images.

I'd like to make a PR to fix this 🙂, but first could I confirm that the expected behaviour is to have assets served at the url specified by the docsUrl attribute?

Thanks!

@amimas
Copy link
Author

amimas commented Jan 26, 2019

While we are on this topic, is it possible to use an 'assets' directory relevant to the docs?

In current setup if I have docs in any subdirectories, and I refer to the assets from '/docs/assets/', it'll work fine. The dev server and built assets will produce static site and show the images. But, if you're viewing the markdown files (those in subdirectories) in github or any editor that can parse the markdown files, they won't be able to show the images. It's probably not that big of a deal since it's easy to work with the dev server. But it'd be useful when you're using wysiwyg type editors.

@avishnyakov
Copy link

avishnyakov commented Jan 29, 2019

Confirming, a same-same issue if docsUrl is used.

It would be very nice if there was a way to use document-relative assets, as @amimas suggested. In this case, both GitHub and VSCode or other editors can render markdown preview straight away. Currently, it feels very much like a guessing game if the image URL is right 🙂

@avishnyakov
Copy link

avishnyakov commented Jan 29, 2019

@marvinchin @yangshun legend! 1.7.2 seems to get the images right!

@yangshun
Copy link
Contributor

All thanks to @marvinchin for fixing it!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants