How to use an old version of a MyST Theme

[choldgraf]

Mini-tutorial for those who want to use a version of the myst-theme other than the latest release.

Normally you specify a theme or template with the site.template option like so:

project:
  ...
site:
  template: article-theme

However, templating allows you to provide full git repositories and refs. Providing a string is really a short-hand for referencing repositories in the myst-templates organization. The configuration above is equivalent to:

project:
  ...
site:
  template: "https://github.com/myst-templates/article-theme.git"

So if you'd like to use an old tag, you should be able to find old commits here and use a template from a specific commit by linking to the .zip file for that commit / tag / etc, like so:

project:
  ...
site:
  template: "https://github.com/myst-templates/article-theme/archive/79a2234133450f53afbf05238d626f728e1a6306.zip
"

[parmentelat]

thanks for the tip @choldgraf
there must be something a little off in the recipe as such though, because I am getting

🔍 Querying template metadata from https://github.com/myst-templates/book-theme/tree/b4f7ed0e437f59750d1702028c2c39cd87e47eaa
Unexpected token '<', "

<!DOCTYPE "... is not valid JSON

To list valid templates, try the command "myst templates list"

the URL I am using here returns a html page, while obvisouly some JSON is expected instead, but I could not guess how to tweak it properly

[agoose77]

For now, you need to use an absolute URL to a ZIP file, e.g.

site:
  template: https://github.com/myst-templates/article-theme/archive/79a2234133450f53afbf05238d626f728e1a6306.zip

In future, I'd like us to support a more structured approach here, e.g. URL + branch fields. That would be a good first issue.

[choldgraf]

Thanks for this! I've updated the explanation at the top

[parmentelat]

indeed, this now works better, thanks ! :)

[parmentelat]

for the record, a proposal for a nicer release mechanism, that would make this (use an old theme version) simpler

• using gh release to publish themes / beneficial for custom themes ? #2317
• support theme URLs that end in .release #2344
• publish through GH releases myst-theme#659