Convert to MySTMD

.gitignore

@@ -2,4 +2,5 @@
 *~
 resources/
 public/
+_build/
 .DS_Store

content/community/onboarding.md

@@ -2,9 +2,9 @@
 title: "Onboarding"
 ---
 
-{{< admonition warning >}}
+:::{warning}
 This is a draft document.
-{{< /admonition >}}
+:::
 
 - Organizing sprints
   - Organising sprints are an excellent way to invite new collaborators, solve issues, gather contributions and broaden the project community. Some helpful tips for organising a sprint efficiently:

content/contributors/first-contribution.md

@@ -113,7 +113,7 @@ git push -u origin [BRANCH NAME]
 
 Enter your GitHub username and password if requested.
 
-{{< admonition note >}}
+:::{note}
 Entering your username and password every time you run `git push` can get tedious!
 Luckily GitHub lets you use an SSH key to authenticate automatically.
 Basically this involves creating two special files: one kept secret on your computer, and one uploaded to GitHub. If you want to set that up, see here:
@@ -123,7 +123,7 @@ Basically this involves creating two special files: one kept secret on your comp
 
 You can also set up an SSH key using the `gh` command-line tool: https://cli.github.com/manual/ if you prefer.
 Mac and Windows users (but not Linux users!) who prefer to use `git` through a GUI can manage authentication using the [GitHub Desktop app](https://desktop.github.com/).
-{{< /admonition >}}
+:::
 
 ### Step 9: Open PR
 

content/contributors/index.md

@@ -0,0 +1,58 @@
+---
+title: "Contributor Guide"
+shortcutDepth: 2
+---
+
+Welcome to the Contributor Guide! Here you will find useful resources that will help you start contributing to the Scientific Python ecosystem.
+
+## First steps
+
+::::{grid} 1 2 2 3
+
+:::{card} Why Contribute
+:link: why-contribute
+Learn some of the reasons why contributing to open source Scientific Python is impactful and can be a transformative experience for developers!
+:::
+
+:::{card} Ways to contribute
+:link: ways-to-contribute
+Learn some of the ways you can contribute to open source Scientific Python projects without having to code.
+:::
+
+:::{card} Choosing a project
+:link: choosing-a-project
+Learn how to choose a project to start contributing to the Scientific Python Ecosystem.
+:::
+
+:::{card} Getting started
+:link: getting-started
+Learn the first steps to contribute to open source Scientific Python.
+:::
+
+:::{card} First contribution
+:link: first-contribution
+Start working on your first contribution to open source Scientific Python.
+:::
+
+::::
+
+## Getting set up
+
+::::{grid} 1 2 2 3
+
+:::{card} Ecosystem
+:link: setup/ecosystem
+Learn how the Scientific Python ecosystem is composed and some of its main packages.
+:::
+
+:::{card} Install
+:link: setup/install
+Learn the tools' intallation process in order to start contributing to the Scientific Python ecosystem.
+:::
+
+:::{card} Next steps
+:link: setup/next-steps
+Start exploring some of the packages from the Scientific Python ecosystem.
+:::
+
+::::

content/documentation/index.md

@@ -0,0 +1,17 @@
+---
+title: "Documentation Guide"
+shortcutDepth: 2
+---
+
+Welcome to the Documentation Guide! Here you will find resources that describe documenting practices relevant to the ecosystem.
+
+## Documentation Authoring
+
+::::{grid} 1 2 2 3
+
+:::{card} Accessible Documentation
+:link: accessible-documentation
+Learn about how to structure and write project documentation that considers disabled and abled readers.
+:::
+
+::::

content/_index.md → content/index.md

@@ -2,41 +2,29 @@
 title:
 ---
 
-{{< grid columns="1 2 2 2" >}}
+::::{grid} 1 2 2 2
 
-[[item]]
-type = 'card'
-title = 'Contributor Guide'
-link = '/contributors/'
-body = '''
+:::{card} Contributor Guide
+:link: /contributors/
 Learn how to join the Scientific Python community!
-'''
+:::
 
-[[item]]
-type = 'card'
-title = 'Development Guide'
-link = '/development/'
-body = '''
+:::{card} Development Guide
+:link: /development/
 Learn recommended tools and approaches for developing Scientific Python libraries.
-'''
+:::
 
-[[item]]
-type = 'card'
-title = 'Lectures Notes'
-link = 'https://lectures.scientific-python.org'
-body = '''
+:::{card} Lectures Notes
+:link: https://lectures.scientific-python.org
 Numerical computing lectures that teach key packages in the scientific Python ecosystem, such as NumPy, SciPy, Matplotlib, scikit-learn, and scikit-image.
-'''
+:::
 
-[[item]]
-type = 'card'
-title = 'Documentation Guide'
-link = '/documentation/'
-body = '''
+:::{card} Documentation Guide
+:link: /documentation/
 Learn recommended approaches for project documentation.
-'''
+:::
 
-{{< /grid >}}
+::::
 
 <!--
       # - buttonText: Maintainer Guide

content/maintainers/_index.md → content/maintainers/index.md

@@ -2,9 +2,9 @@
 title: "Maintainers"
 ---
 
-{{< admonition warning >}}
+:::{warning}
 This is a draft document.
-{{< /admonition >}}
+:::
 
 The scientific Python ecosystem welcomes your expertise and enthusiasm!
 

content/maintainers/interacting-with-new-contributors.md

@@ -3,9 +3,9 @@ title: "How to interact with new community
 members"
 ---
 
-{{< admonition warning >}}
+:::{warning}
 This is a draft document.
-{{< /admonition >}}
+:::
 
 As a maintainer, you will be the first point of
 contact for new community members. It is important

content/maintainers/managing-conflict.md

@@ -2,9 +2,9 @@
 title: "Managing conflict"
 ---
 
-{{< admonition warning >}}
+:::{warning}
 This is a draft document.
-{{< /admonition >}}
+:::
 
 ### Code of Conduct
 

content/maintainers/meeting_types.md

@@ -2,9 +2,9 @@
 title: "Meeting types"
 ---
 
-{{< admonition warning >}}
+:::{warning}
 This is a draft document.
-{{< /admonition >}}
+:::
 
 With growth and sustainability in mind, every OSS project would benefit from holding the following recurring meetings:
 

docs/decisions/0001-myst-migration/0001-migrate-to-mystmd.md

@@ -0,0 +1,71 @@
+# ADR 0001 — Migrate build system from Hugo to MyST-MD
+
+Date: 2026-05-11
+Accepted: 2026-05-18
+Status: Accepted
+Branch: lb/myst-migration
+Issue: scientific-python/scientific-python.org#846
+
+## Context
+
+`learn.scientific-python.org` builds with Hugo via `make html` and deploys via
+Netlify (auto-deploy on push to `main`). We want to convert the content files
+to MyST syntax.
+
+Three realistic MyST toolchain options exist. They are not equivalent:
+`jupyter-book` is a higher-level tool built on top of `mystmd`; `mystmd` is the
+underlying engine and is available as both a Node package (npm) and a Python
+package (pip/conda) that bundles Node internally.
+
+## Decision
+
+Replace Hugo with **`mystmd` Python package** (`pip install mystmd`,
+`myst build --html`) as the build tool.
+
+## Options considered
+
+| Option                                             | Pros                                                                                                                                                                                                                                                   | Cons                                                                                                                                                                                                                                                    |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Stay on Hugo**                                   | Theme parity with sibling SP sites; no content changes needed                                                                                                                                                                                          | Hugo is not Python; MyST content conversion still desirable long-term                                                                                                                                                                                   |
+| **jupyter-book 2.x**                               | Pure Python (`pip install jupyter-book`); SP ecosystem familiar with JB; conda-forge package; handles notebook execution natively                                                                                                                      | Wraps `mystmd` under the hood — extra abstraction; config format (`_config.yml`, `_toc.yml`) is not portable to plain `myst.yml` if JB is dropped later; JB 2.x released late 2024 — docs and community experience thin; feature lag vs direct `mystmd` |
+| **mystmd — Node CLI** (`npm install mystmd`)       | Native runtime; latest npm releases immediately; same `myst.yml` config; active ExecutableBooks development                                                                                                                                            | Requires Node.js in every build environment (Netlify, RTD, CI); unfamiliar to Python contributors                                                                                                                                                       |
+| **mystmd — Python package** (`pip install mystmd`) | Python-centric install (pip/conda-forge); bundles Node internally — no separate Node needed; same `myst.yml` config as Node CLI (no extra abstraction layer); proven by `tools.scientific-python.org` PR #81; works on all considered deploy platforms | Node bundled internally — slightly opaque; PyPI/conda releases may lag npm by 1–7 days                                                                                                                                                                  |
+
+## Rationale for proposed decision
+
+**Why not jupyter-book:** `learn.scientific-python.org` contains no Jupyter
+notebooks; JB's primary value (notebook execution, Sphinx integration) does not
+apply here. JB 2.x uses `mystmd` as its build engine, so the team would get
+`mystmd` indirectly with an extra config layer on top. The JB config format
+(`_config.yml`, `_toc.yml`) is not portable — if JB were dropped later, the
+config would need to be rewritten to `myst.yml` from scratch.
+
+**Why not the Node CLI:** Requires Node.js in every build environment. SP
+contributors and maintainers work in Python environments; npm is unfamiliar and
+adds friction for new contributors. The Python package provides identical
+functionality without any Node setup.
+
+**Why the Python package:** Fits SP's Python-centric workflow; `conda install
+-c conda-forge mystmd` works for conda users. No Node.js needed in Netlify,
+RTD, or GitHub Actions (Node is bundled inside the package). The `myst.yml`
+config is identical to the Node CLI — switching delivery method later is a
+one-line change.
+
+## Installation
+
+For Netlify builds and RTD: `pip install mystmd` (no Node configuration needed
+in `netlify.toml`; see ADR 0007).
+
+Local dev: install via any preferred method (pip, conda, npm — developer's
+choice). The repo does not mandate a specific local environment.
+
+## Consequences
+
+- `myst build --html` replaces `make html` (Hugo)
+- `pip install mystmd` is the chosen delivery method; no Node toolchain required
+  in CI or `netlify.toml`
+- The `scientific-python-hugo-theme` submodule is removed (see ADR 0003)
+- `netlify.toml` is updated to use `mystmd` (see PLAN.md Phase 6)
+- Nine content files require shortcode conversion (see ADR 0002)
+- Footer/quicklinks are not yet supported in MyST default templates (see ADR 0005)
+- Other SP repos remain on Hugo until they choose to migrate (see ADR 0006)