Layout broken when using jupyter book build --html in v2

[johannamay]

Dear jupyter book developers and users,

I upgraded from v1 two weeks ago. At first everything seemed to work. But now I get a problematic layout. When using "jupyter book start" layout looks fine. But when using "jupyter book build --html" I get the attached view and all the links are broken. I have been searching desperately for any solution. I tried to comment a great part of my toc. I tried to use a simple myst file with just the README.md as a starter. But none of these has worked out. I still cannot figure out how to have the normal layout (book-theme).

How can I debug this?

Do I really need to delete all my files away from the project and start from scratch and rebuild everything?

Or is the problem, that .md files are no longer allowed as starting points?

Please, point me at the right place for the instrutions on how to build a html export (that will then be deployed on gitlab, but the same problem happens there as on my laptop ...). Is it a versioning problem with the python files or other files?

Thank you.

J

[choldgraf]

This is often a problem with BASE_URL not being set in your build environment. See if these docs help:

https://mystmd.org/guide/deployment-github-pages#base-url-configuration-for-github-pages

[johannamay]

Thank you, Chris, for the hint. Where do I set BASE_URL if I want to provide a zip-file with the html folder and tell people to open index.html for the start? And where do I set BASE_URL when deploying on gitlab? The thing is, at the beginning I could create a static webfolder and open the index.html and that worked, both on my local machine and on gitlab. Now it does not work anymore and there must be some setting or some file or whatever that irritates the build. But I could not find out which one, unfortunately. Best, J

[choldgraf]

do these docs help? https://mystmd.org/guide/deployment#deploy-base-url

[johannamay]

Hi Chris, thank you for the hint. This works now if I use gitlab CI. But I still have an open issue here: I also need a version that can be "deployed" by creating a zip-Folder for persons with an institutional computer (no admin rights, no special software except for web browser installed). Then I will ask them to open the index.html file. How can I set a BASE_URL for these people? Would "." work? The thing is that, in a project, we have a review process that involves moving files across platforms like MS teams and email. And if they need to install npm, software clearance and getting necessary admin rights will take them too long. The other thing is that I want to deploy the material in the future on a personal website without gitlab CI. How would that work? Cheers and thank you so much for your fast help! J Am Samstag, 15. November 2025 um 15:54 schrieb Chris Holdgraf ***@***.***> ...

…

This is often a problem with BASE_URL not being set in your build environment. See if these docs help: https://mystmd.org/guide/deployment-github-pages#base-url-configuration-for-github-pages — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.