Convert to MySTMD

[lundybernard]

Convert this site and sub-sites to mystmd.

Advantages of MySTMD and expected benefits

• Better community support from the scientific python community/ecosystem than other options.

• Further the development of MySTMD as early-adopters:

  • R&D spike to test viability and provide feedback to the MySTMD dev team
  • Identify issues with the conversion process and address them

• Cross-references to other myst-based sites

  • ref: https://mystmd.org/guide/external-references

---

Sub-sites:
learn
tools
cookie
blog
lectures

[lundybernard]

MyST Migration: Site Inventory & Conversion Overview

Top-level view of all sites in scope, their stacks, migration status, and key conversion challenges. See learn PR #315 for the working example and ADRs driving the decisions below.

---

Site inventory

Site	Repo	Stack	Issue	Status
scientific-python.org	scientific-python/scientific-python.org	Hugo	#846	No PR
learn.scientific-python.org	scientific-python/learn.scientific-python.org	Hugo	#279	PR #315 in progress
tools.scientific-python.org	scientific-python/tools.scientific-python.org	Hugo	#77	PR #81 open (stale)
blog.scientific-python.org	scientific-python/blog.scientific-python.org	Hugo	—	No issue or PR
cookie (dev guide)	scientific-python/cookie	Jekyll	#742	No PR
lectures.scientific-python.org	scipy-lectures/scientific-python-lectures	Jupyter Book	—	Already on MyST syntax; relationship to SP org to be confirmed

---

Hugo sites: shortcode conversion

All four Hugo sites share the scientific-python-hugo-theme and the same shortcode set. The canonical mappings are defined in ADR 0002 (in PR #315 under docs/decisions/0001-myst-migration/); the table below extends that to cover shortcodes not present in learn.

Hugo shortcode	MyST	Repos	Notes
{{< grid >}} / [[item]]	::::{grid} + :::{card}	all	Covered in ADR 0002
{{< admonition warning|note >}}	:::{warning} / :::{note}	learn, sp.org	Standard types; direct
{{< admonition mission|values >}}	:::{admonition} Mission	sp.org	Named types → arbitrary-title admonition
{{< grid file="x.toml" />}}	No built-in equivalent	sp.org, tools, blog	TOML-driven people grids — needs custom plugin or inline conversion
{{< blog >}}	No built-in equivalent	blog	Post listing — needs theme or plugin support

grid file= and {{< blog >}} are the two open design questions. learn was chosen as the starting point because it uses neither.

---

cookie (Jekyll → MyST)

cookie uses custom Liquid plugins (_plugins/tabs.rb, _plugins/details.rb) with no Hugo equivalent.

Jekyll	MyST	Notes
{% tabs %} / {% tab label Title %} / {% endtabs %}	::::{tab-set} + :::{tab-item} Title :sync: label	label arg → :sync: key for cross-set sync
{% tabbodies %}	::::{tab-set} with :sync: keys	Requires page restructure — see below
{% details Title %}	:::{dropdown} Title	Direct
{% include file.md %}	{include} file.md	Direct
{% rr CODE %}	Custom MyST role	cookie-specific lint rule reference; domain-specific, not a blocker

{% tabbodies %} note: cookie splits tabs across two blocks — {% tabs %} renders the header bar, {% tabbodies %} renders the bodies elsewhere on the page. MyST's {tab-set} always renders as a single unit. Migration strategy: merge each {% tabs %} + {% tabbodies %} pair into one {tab-set} with matching :sync: keys. Functionally identical when rendered; requires per-page judgment rather than mechanical substitution.

---

lectures (Jupyter Book → MyST-MD)

lectures (_config.yml) already uses MyST syntax — .md files with MyST directives and Jupyter notebooks via jupytext. The migration is a build-tool swap (jb → myst CLI), not a content conversion. Key risks: sphinx_exercise extension has no confirmed MyST-MD equivalent, and the JupyterLite integration needs verification.

I don't think we will be converting the lectures site, since it is very notebook centric.

---

Suggested sequencing

1. learn — simplest Hugo case; PR #315 in progress. Establishes the pattern for all Hugo sites.
2. tools — next simplest; PR #81 can be rebased on learn's work. First test of grid file= conversion.
3. scientific-python.org + blog — both need the grid file= solution; blog additionally needs a post-listing solution.
4. cookie — independent Jekyll migration; can proceed in parallel once the tab mapping is agreed on.
5. lectures — scope to be confirmed; lowest content risk, highest build-tooling uncertainty.

---

AI tools disclaimer: this report was researched and drafted using Claude Sonnet 4.6, with a review pass by Claude Opus 4. Source verification was performed against the live repos. I have read and reviewed the content and believe it to be accurate. Since scientific-python.org does not have an official AI use policy, I am using the SciPy project's policy as a guideline.