Should it be possible to view rendered html files?

[da5nsy]

See: the-turing-way/the-turing-way#4268

Should it be possible to run jupyter-book build --html and then just open and view the html files as though you were browsing a live site? Or is it necessary to use jupyter-book start instead if you want to view the output locally?

[choldgraf]

IMO it should be possible. The first step to take is to figure out if there's a way to make this work with the proper configuration (eg maybe the BASE_URL is wrong?). If we figure that out, we can document it.

[agoose77]

To extend @choldgraf yes AND no.

The base url needs to match, which likely will require a server if you're e.g just opening an HTML file from your file system.

We also expect extension-free link support, like /foo.

In future, we would like to drop this base URL dependence, but it's limited by the tooling at the moment.

[stefanv]

You need to run a web server to make this work for the two reasons listed plus one:

1. Serving documents at correct base URL
2. You need to be able to redirect /foo to /foo.html
3. You need to host the static JS files that the browser needs (this is why you cannot just open the directory in your browser directly)

I have a simple Python server script that can do all of the above, but given that myst start already does it, what is the exact requirement here—previewing the static build output without uploading it?

[da5nsy]

what is the exact requirement here

I wouldn't say it's a requirement - myst start is fine - it's just that we used to be able to do it with JB1 (I think? I'd need to check) and now we can't. I put in a PR to remove the suggestion from our docs (that one could simply open the html), and @JimMadge asked me why we can't do that anymore.

[JimMadge]

Suspected it was something to do with base URL, but it sounds like it is a bit more complex than just that.

To clarify, @da5nsy and I both saw the same behaviour and I wanted to make sure we understood what was happening, and that we hadn't configured something incorrectly. I think this is fairly in line with static site generators. myst start is more convenient for local development anyway, so I think that is how we should update our docs 👍.

Thanks for the information @choldgraf @agoose77 and @stefanv 🙏

[stefanv]

We should be able to get a fair way by using relative URLs, so maybe that's a good starting point.