feat: enable downloadable .ipynb from unstable .md notebooks

- Generate .ipynb from .md at build time via jupytext (md:myst format)
- Update myst.yml TOC to reference generated .ipynb for unstable section
- Add jupytext conversion step to GitHub Actions CI pipeline
- Gitignore unstable/*.ipynb (only .md tracked in repo)
- Document new pipeline in AGENTS.md

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

.github/workflows/notebook_to_html.yml

@@ -34,6 +34,19 @@ jobs:
       # Checks out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@v4
 
+      # Convert unstable/*.md → unstable/*.ipynb so the site provides "Download notebook" buttons
+      # https://jupytext.readthedocs.io/ — supports md:myst format natively
+      # Must run BEFORE build so myst/jupyter-book can pick up the generated notebooks
+      - name: Generate downloadable notebooks
+        run: |
+          pip install jupytext
+          for f in unstable/lesson*_tutorial.md unstable/lesson*_exercise_answers.md; do
+            [ -f "$f" ] || continue
+            out="${f%.md}.ipynb"
+            python -m jupytext --from md:myst --to notebook --output "$out" "$f"
+            echo "Generated: $out"
+          done
+
       # Runs a set of commands using the runner's shell
       # https://mystmd.org/guide/deployment-github-pages#fn-except-custom-domains
       - name: Install dependencies and build page

AGENTS.md

@@ -96,6 +96,22 @@ This script:
 - **`%%capture` magic IS supported** in MyST text notebooks. MyST uses a Jupyter Server with an IPython kernel to execute code cells ([Execute Notebooks at Build Time](https://mystmd.org/guide/execute-notebooks)). The `%%capture` magic is a built-in IPython cell magic ([Built-in magic commands — IPython](https://ipython.readthedocs.io/en/stable/interactive/magics.html)) and works correctly during MyST execution.
 - If output suppression is needed without `%%capture`, the MyST-native approach is to use cell tags like `remove-stdout` and `remove-stderr` on the `{code-cell}` directive.
 
+### Downloadable `.ipynb` from `.md` notebooks
+
+The `unstable/` `.md` files are the canonical source. `.ipynb` files are generated at build time so visitors can download them:
+
+1. **CI pipeline** (`.github/workflows/notebook_to_html.yml`) runs `jupytext --from md:myst --to notebook` before the MyST build, converting each `unstable/*.md` → `unstable/*.ipynb`.
+2. **`myst.yml` TOC** references the generated `.ipynb` for the unstable section — MyST renders these identically to the `.md` but provides native "Download notebook" buttons.
+3. **`unstable/.gitignore`** excludes `*.ipynb` so only `.md` is tracked in git.
+
+To generate locally (e.g. for testing):
+```bash
+pip install jupytext
+for f in unstable/lesson*_tutorial.md unstable/lesson*_exercise_answers.md; do
+  python -m jupytext --from md:myst --to notebook --output "${f%.md}.ipynb" "$f"
+done
+```
+
 ---
 
 ## Building & Testing
@@ -108,7 +124,7 @@ python3 -m venv venv
 source venv/bin/activate
 
 # For MyST text notebook builds:
-pip install mystmd jupyter-server ipykernel
+pip install mystmd jupyter-server ipykernel jupytext
 
 # For legacy jupyter-book builds:
 pip install jupyter-book --pre
@@ -118,6 +134,13 @@ pip install jupyter-book --pre
 
 **MyST build (root — includes all lessons + unstable):**
 ```bash
+# Step 1: Generate .ipynb from .md (required for unstable section)
+pip install jupytext
+for f in unstable/lesson*_tutorial.md unstable/lesson*_exercise_answers.md; do
+  python -m jupytext --from md:myst --to notebook --output "${f%.md}.ipynb" "$f"
+done
+
+# Step 2: Build the site
 myst build --html
 ```
 - `--execute` runs all code cells and caches results in `_build/execute/`

myst.yml

@@ -49,17 +49,17 @@ project:
     - title: "Unstable"
       children:
         - file: unstable/README.md
-        - file: unstable/lesson0_tutorial.md
-        - file: unstable/lesson1_tutorial.md
-        - file: unstable/lesson2_tutorial.md
-        - file: unstable/lesson3_tutorial.md
-        - file: unstable/lesson4_tutorial.md
-        - file: unstable/lesson5_tutorial.md
-        - file: unstable/lesson1_exercise_answers.md
-        - file: unstable/lesson2_exercise_answers.md
-        - file: unstable/lesson3_exercise_answers.md
-        - file: unstable/lesson4_exercise_answers.md
-        - file: unstable/lesson5_exercise_answers.md
+        - file: unstable/lesson0_tutorial.ipynb
+        - file: unstable/lesson1_tutorial.ipynb
+        - file: unstable/lesson2_tutorial.ipynb
+        - file: unstable/lesson3_tutorial.ipynb
+        - file: unstable/lesson4_tutorial.ipynb
+        - file: unstable/lesson5_tutorial.ipynb
+        - file: unstable/lesson1_exercise_answers.ipynb
+        - file: unstable/lesson2_exercise_answers.ipynb
+        - file: unstable/lesson3_exercise_answers.ipynb
+        - file: unstable/lesson4_exercise_answers.ipynb
+        - file: unstable/lesson5_exercise_answers.ipynb
 
 site:
   template: book-theme

unstable/.gitignore

@@ -1,2 +1,5 @@
 # MyST build artifacts
-_build/
+_build/
+
+# Generated .ipynb files (converted from .md at build time via jupytext)
+*.ipynb