jupyter-book / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
191 stars 61 forks source link

Allow `myst build` without downloading web assets for low-internet situations #1451

Open choldgraf opened 1 month ago

choldgraf commented 1 month ago

Currently when you run myst start, it queries a number of web-based sources for things like cross-references and embeds. This becomes a problem if you have really slow or non-existent internet (like on planes). Running myst start either hangs indefinitely, or results in an error like so:

Error loading template information from https://api.mystmd.org

This makes it impossible to preview MyST content locally until you get internet access again.

We should allow users to preview MyST sites using only local assets if possible, so that they aren't blocked by the lack of fast internet.

Ideas for solutions

We could have a --no-download flag that tells MyST not to attempt downloading anything from the web, and just get on with rendering a site locally for previews. This wouldn't work if the theme wasn't yet downloaded but that should be an acceptable edge case.

agoose77 commented 1 month ago

Currently when you run myst start, it queries a number of web-based sources for things like cross-references and embeds. This becomes a problem if you have really slow or non-existent internet (like on planes). Running myst start either hangs indefinitely, or results in an error like so:

:100:

I had this exact scenario on the way to SciPy, but I pre-cached the various assets. That required me to actively plan my travel, knowing how the tools works.

An orthogonal change that would improve many people's workflows would be to use system-level caching of the templates, which would reduce the time to spin up a new MyST project. It would solve the problem of being a MyST user that spins up a new project on a flight; the system cache would provide the templates.

Related to this, we need to think about versioning/version control of themes, so that in the future we can avoid breakages as things move independently.

As for network availability, Nix detects whether the system has a network connection and uses that to avoid trying to resolve things remotely. We could do the same, and prefer a shipped-with-myst version of the default themes. I assume the check involves a DNS query.