How to version/deploy mystmd website?

[sneakers-the-rat]

Taking a little curiosity poke around making a myst website for lab meeting slides, and i'm a little curious how I'm intended to version/deploy this.

After doing the myst init I have a myst.yml and _build directory that has site and templates subdirectories. It looks like the default book template was cloned into the templates directory, and it has all of the assets along with it. This seems like a lot to commit to the repo, as eg. book-theme also has a book-theme-main subdirectory that has a second copy of a lot of the thebe-lite minified js files, etc. I would just .gitignore them and do the installation in my github actions workflow for deploying to gh pages but then I'm not sure how to override the default template. To be clear - i'm not having trouble actually getting the page to build or doing the deployment to gh pages, my question is just about intended usage :)

For reference, I've used jekyll for a long time, as well as jupyter-book, etc. and typically the content of the page is kept separate from the templates which are kept separate from the built page. In Jekyll, I can override any individual part of the template by just making a file with the same name in a _layouts or _includes directory, so I don't have to have the whole theme in my repository.

Curious what the intended usage is - should I just suck it up and commit the whole thing to the repo?

[riziles]

@sneakers-the-rat , I think it depends on how you are serving the website. i.e. if you are going to serve directly with Node by using myst start from an AWS instance or something, you'd probably want to gitignore the build folder. If you have some other method to serve static html, you should use myst build --html, and you may want to commit the contents of that _build/html folder to a separate branch or repo. There are pretty good instructions for some deployment scenarios here: https://mystmd.org/guide/deployment#deploying-to-github-pages and here: https://mystmd.org/guide/deployment#deploying-to-curvenote . I highly recommend Curvenote . A number of Curvenote employees are core maintainers on this project and in general very helpful.

[sneakers-the-rat]

right right, as I said I have no problem deploying. I'm just looking to build a static site and serve it through gh pages, so _build/html would be something that I generate as a build artifact rather than committing directly to the repo in any case. My question concerns whether _build/templates should be, or how one is intended to override templates/generally mix user content with themes in a source repo

[rowanc1]

Everything in the _build folder can/should be ignored by git as it can be recreated or is pulled in dynamically. The templates that currently exist are built using Remix/React and are in myst-theme git repository. You can see the book-theme. The contents of your _build/templates/site folder are build assets and are not intended to be edited directly. The themes are still evolving, especially with the computational content. There is a blog article here that describes a bit about the themes:
https://curvenote.com/blog/architecture-of-a-myst-website

You can dive into creating your own theme or tweaking it. To use it with your content you can do a myst start --headless with your content and then a npm run theme:book in the myst-theme repo: any edits should show up live. Some lite docs are in the readme for that, but happy to elaborate and improve the docs!

We will make it easier to pull out pieces of the theme in the future as well as customize various parts through configuration. If you have suggestions of something you would like to see, let us know! :)

[LecrisUT]

From the experimentation on #982, RTD seems to handle version control by default, although there are some issues to resolve:

• RTD: Redirect pages to .html files #984 pages do not seem to be automatically navigable. This might depend on your hosting environment
• Themes, templates, etc. are not shared among versions. This makes it easier to test different themes though, so it's up to the user to decide what model to implement
• Need more investigation on how the Flyout wheel ¹ and other addons work. It sometimes seem to work, sometimes not 🤔

Footnotes

1. https://blog.readthedocs.com/addons-flyout-menu-beta/ ↩