Unclear where to set BASE_URL environment variable

[paulskrzypczyk]

Dear mystmd team,

I have been deploying a mystmd site using the github action, and everything has been working fine. I saw that I hadn't been ignoring the _build folder in github, and so updated to ignore this. The next time I deployed, the site does not view properly at all. I removed the _build from gitignore, and it again builds properly.

I believe that the root of this problem may have to do with the BASE_ENV environment variable, as explained in https://mystmd.org/guide/deployment#deploying-to-github-pages

However, I was not able to understand how to fix the problem, as in the box on BASE_URL, it does not say where I am supposed to add "export BASE_URL="/repository_name", and I wasn't able to figure this out. Please could I request further information, and suggest that the website is updated to be more precise here.

I am a university lecturer, and I have been trying to deploy a myst version of my lecture notes inside my learning environment (more precisely, I have asked the digitial education team at my university to assist in this). They were unable to get this to work, after I provided them with the output from "myst build --html". I wonder if this same issue with the BASE_URL is causing the problems for them (when I run npx serve _build/html" on my local machine everything works fine). I'm hoping that once I understand how to resolve the issue with the base URL, it might fix both problems simultaneously,

Many thanks

Paul

PS I want to say a huge thank you, as what you're doing with MyST is absolutely awesome! I can't believe how straightforward it was to build a website. I genuinely had the same butterflies as when I compiled my very first latex document (I also found that remarkable, how easy it was to get mathematical outputs so easily).

[paulskrzypczyk]

sorry - I thought I posed this to the mystmd repo, not the general executablebooks repo. I don't seem to be able to move it myself.

[rowanc1]

Thanks for opening a discussion @paulskrzypczyk, and glad that the first experience was led to butterflies. 🦋 🚀

The export BASE_URL="/repository_name" should be run in a shell before you run myst build --html and the /path should ultimately match where it is served from on the end website. For example, .github.io repos have no extra base url (i.e. '') and if you are copying the HTML from your machine onto a different hosting solution, it must match. This means that on your computer the build will not be styled correctly, but when deployed it should.

If your content is inside of a learning environment, you will need to know the base path that it is on (e.g. https://myuniversity.edu/course/identifier/static), set export BASE_URL="/course/identifier/static" in your terminal then build the HTML (myst build --html), and then upload that to the course. 🤞

There are a few other things that could be going on depending when you installed. (1) the template could be out of date (myst clean --templates) will fix that. (2) you could have a projects list in the site config, there is a bit in the docs on how to fix that under "Static sites should have an index.html" here.

I hope that helps, haven't seen a myst site deployed in a LMS yet, so we might need to tweak a few things if that doesn't work. Once we get this working we can update the docs!