Activity

1. lundybernard commented on May 18, 2026

   

   lundybernard

   on May 18, 2026

   Last edited by lundybernard

   Author

   More actions

   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.