Problem loading assets in mkdocs deployed on github pages

danimrprofe commented 1 year ago

Contribution guidelines

[X] I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

[X] ... the problem doesn't occur with the mkdocs or readthedocs themes
[X] ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
[X] ... the documentation does not mention anything about my problem
[X] ... there are no open or closed issues that are related to my problem

Description

Hello, don't know if this is the right place to ask for help, but i'm having a little problem and can't find the solution to it. By the way, love mkdocs and the material theme and I would appreciate if you could help me.

Mkdocs works perfect when served locally (localhost), but displays without styles or images when deployed to github.

Thank you in advance, if more information is needed please let me now.

Expected behaviour

I installed mkdocs, initiated a new project in a repo and configurated the yaml as the guide said. mkdocs serves works perfect as in local server everything displays as expected. Then I deploy with the command with the option gh-deploy on mkdocs but on github doesn't load assets images or styles, only the HTML.

Actual behaviour

This is where the build shoud deploy the website. I did it from command line via mkdocs command, and it pushed to the new branch of the repository (gh-deploy)

https://danimrprofe.github.io/apuntes/

As you can see no styles ar shown:

This is how the website is displayed (without styles). Seems to be looking at the media in the root of the URL, where they are not. I mean, the HTML looks for:

https://danimrprofe.github.io/assets/images/favicon.png

Instead of where it really is:

https://danimrprofe.github.io/apuntes/assets/images/favicon.png

My pages options in the repo.

Steps to reproduce

Build with mkdocs
Deploy with gh-deploy
Check in the github.io page.

Package versions

Python: Python 3.8.2
MkDocs: mkdocs, version 1.4.2
Material: Version: 8.5.10

Configuration

site_name: My Docs

theme:
  name: material
  language: es
  features:
    - navigation.tabs
    - navigation.tabs.sticky

System information

Operating system: windows 10
Browser: all

squidfunk commented 1 year ago

Thanks for reporting. When deploying, you need to specify site_url – it must point to your GitHub URL:

https://github.com/squidfunk/mkdocs-material/blob/80b4a4c8aca25cfec059806a6877658ff60a4154/mkdocs.yml#L23

The reason is that MkDocs will resolve asset URLs relative to the configured site URL. If no site URL is configured, / is assumed, so your project is expected to live at the root of the current URL. Since your documentation is hosted in a subdirectory, this setting is mandatory. I'll add a note to the GitHub Pages deployment guide.

danimrprofe commented 1 year ago

Thank you very much for your suport, it worked perfectly!!!!

squidfunk / mkdocs-material