Docusaurus: CSS and IMG not loading in GitHub Enterprise Pages

[theletterf]

🐛 Bug Report

I work in a GitHub Enterprise environment. Publishing, as implemented by #689 , works well. Files are pushed to the repo with the same folder structure as in local. The site loads well in localhost:3000.

The problem is that the static pages reference '/css/main.css' instead of '../css/main.css'. The CSS is there. This happens with custom CSS and images, too. If I manually tweak the path to '../css/', the site renders as intended. I troubleshooted this with @endiliey on Discourse, but we couldn't find the root cause.

This may be similar to #448 .

Have you read the Contributing Guidelines on issues?

Yes.

To Reproduce

1. Set up a new Docusaurus project using the stable version.
2. Edit siteConfig.js to add githubHost. Set baseUrl to '/'.
3. Run publish-gh-pages.
4. Load any page inside {githubHost}/pages/{organizationName}/{projectName}/docs/

Expected behavior

CSS should load fine and styles should be applied to the static pages. Images put under /website/static/img should load.

Actual Behavior

Pages load without styles nor images.

[endiliey]

This is caused due to how / resolves in GitHub Enterprise

Example:
/css/main.css in https://reasonml.github.io/ will resolve to https://reasonml.github.io/css/main.css

/css/main.css in https://git.company.com/pages/username/repo actually resolves to https://git.company.com/css/main.css instead of https://git.company.com/pages/username/repo/css/main.css

I think baseUrl in this case shouldn't be / but /pages/username/repo/

[theletterf]

I fixed this by changing the baseUrl from / to

https://{githubHost}/pages/{organizationName}/{projectName}/

In other words, I had to specify the full URL. That, I think, is not the expected behavior. The documentation should be updated to reflect that. Or #689 be fixed.

[endiliey]

Did you try /pages/{organizationName}/{projectName}/ ?

[JoelMarcey]

Hi @theletterf - The baseUrl should generally not have a full URL, including http(s) associated with it -- can you try what @endiliey mentioned above?

[theletterf]

@endiliey @JoelMarcey It works that way :-)

[endiliey]

This is because GH Enterprise serve from one endpoint which is {githubHost} so the baseUrl should be set as according.

Closing this.

P.S We accept better documentation PR for https://docusaurus.io/docs/en/site-config.html#mandatory-fields documentation on https://github.com/facebook/docusaurus/edit/master/docs/api-site-config.md
😉

[stephen-james]

Hi All, while the solution from @endiliey works for publishing (to GH Pages), I've found that when I run locally I need to use a baseUrl of / in order to serve images correctly.

The MD image links I am using are in the format:

![alt text](/docs/assets/{image-file.png})

I believe this is a side effect of applying the baseUrl in local development mode as per this commit : https://github.com/facebook/Docusaurus/commit/e619884921403024101485b2e8bffe34205c4617

I suppose I could use relative image urls ![some alt text](assets/{image-file.png}) but this would go against the docs in https://docusaurus.io/docs/en/doc-markdown#linking-to-images-and-other-assets

Another option may be if we introduce another baseUrl for when running a local development server... ie:

        ...
        baseUrl: '/pages/{organizationName}/{projectName}/',
        localBaseUrl: '/',
        ...

or maybe modifying the index.html template to use a <base> tag could help?

If you feel any of these approaches may be feasible I can investigate further and PR.

Thanks!!

[endiliey]

@stephen-james

You should link the image with ![some alt text](assets/{image-file.png}) or even better -> ![alt text]({baseUrl}docs/assets/{image-file.png})

Referring (assets/ will be replaced to {baseUrl}/docs/assets/
https://github.com/facebook/Docusaurus/blob/22f3a85a494ddf46bc29964a7989335a7dba4a9a/lib/server/docs.js#L79-L83

The RAW Markdown is below:
https://github.com/facebook/Docusaurus/blob/master/docs/api-doc-markdown.md

It got transformed into {baseUrl}/docs/assets/ in the website as a side effect 😭