fschuch · Copilot · Feb 3, 2026 · Feb 9, 2026 · Feb 9, 2026 · Feb 9, 2026
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -37,8 +37,6 @@ jobs:
         uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
 
       - name: Build the book
-        env:
-          SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
         run: hatch run docs:build
 
       - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
@@ -63,4 +61,4 @@ jobs:
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: build/_build/html
+          publish_dir: build/html
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,60 @@
+# Migration to Jupyter Book 2.x
+
+This document describes the migration from Jupyter Book 1.x (Sphinx-based) to Jupyter Book 2.x (MyST-based).
+
+## What Changed
+
+### Architecture
+- **Jupyter Book 1.x**: Built on Sphinx (Python-based document engine)
+- **Jupyter Book 2.x**: Built on MyST Document Engine (JavaScript/TypeScript-based)
+
+### Configuration Files
+- `_config.yml` and `_toc.yml` → consolidated into `myst.yml`
+- Old configuration files backed up as `._config.yml.bak` and `._toc.yml.bak`
+
+### Build Commands
+- **Before**: `jupyter-book config sphinx docs && jupyter-book build docs`
+- **After**: `jupyter-book build docs`
+
+### Removed Features
+
+The following Sphinx-specific features are no longer available in Jupyter Book 2.x:
+
+1. **sphinx-github-changelog extension**: The automated changelog generation from GitHub releases is not supported. Users should refer to [GitHub Releases](https://github.com/fschuch/wizard-template/releases/) directly.
+
+2. **Sphinx autodoc**: Automatic API documentation generation from Python docstrings is not available. The API reference has been simplified to point users to the source code.
+
+3. **Bibliography support (.bib files)**: The `references.bib` file is no longer processed by the build system.
+
+4. **Custom Sphinx directives**: Some directives like `:link-type:`, `:class-header:`, `:class-container:`, and `:gutter:` options in grids have been removed as they're not supported in MyST.
+
+5. **RST files**: All reStructuredText (.rst) files have been converted to Markdown (.md) format.
+
+### What Still Works
+
+- MyST Markdown syntax (CommonMark + extensions)
+- Jupyter notebooks
+- Cross-references
+- Grid layouts (with simplified options)
+- All other MyST-supported directives and roles
+
+## Benefits of the Migration
+
+1. **Modern Architecture**: Built on modern JavaScript/TypeScript tooling
+2. **Better Performance**: Faster builds with incremental compilation
+3. **Improved Web Experience**: Better interactive features and responsive design
+4. **Unified Configuration**: Single `myst.yml` file instead of multiple config files
+5. **Active Development**: Jupyter Book 2.x is the actively maintained version
+
+## Known Limitations
+
+- No Sphinx extension support (including custom plugins)
+- Bibliography/citations require different approach
+- API documentation needs manual maintenance or alternative tools
+- Some advanced Sphinx features not yet available in MyST
+
+## Further Reading
+
+- [Jupyter Book 2.x Documentation](https://jupyterbook.org/stable/)
+- [MyST Markdown Guide](https://mystmd.org/guide)
+- [Upgrade Guide](https://jupyterbook.org/stable/resources/upgrade/)
diff --git a/docs/_config.yml → docs/._config.yml.bak b/docs/_config.yml → docs/._config.yml.bak
diff --git a/docs/_toc.yml → docs/._toc.yml.bak b/docs/_toc.yml → docs/._toc.yml.bak
diff --git a/docs/intro.md b/docs/intro.md
@@ -1,16 +1,11 @@
 # Wizard Template's Documentation
 
-```{centered} _Let the wizard do the heavy lifting so you can focus on your craft_
-```
+_Let the wizard do the heavy lifting so you can focus on your craft_
 
 ::::{grid} 1 1 2 3
-:class-container: text-center
-:gutter: 3
 
 :::{grid-item-card}
 :link: getting-started/about
-:link-type: doc
-:class-header: bg-light
 
 Project Management 🧙🏻‍♂️
 ^^^
@@ -21,8 +16,6 @@ This is a general-purpose template that aims to provide a magical start to any P
 
 :::{grid-item-card}
 :link: user-guide/tooling/index
-:link-type: doc
-:class-header: bg-light
 
 Quality Assurance ✅
 ^^^
@@ -33,8 +26,6 @@ Use pre-commit hooks, linters, formatters, and unit tests to ensure your code is
 
 :::{grid-item-card}
 :link: user-guide/documentation
-:link-type: doc
-:class-header: bg-light
 
 Documentation 📚
 ^^^
@@ -45,8 +36,6 @@ Write documentation with Jupyter Book, including API references, interactive tut
 
 :::{grid-item-card}
 :link: user-guide/versioning-changelog
-:link-type: doc
-:class-header: bg-light
 
 Versioning/Changelog 📜
 ^^^
@@ -56,8 +45,6 @@ Commitless versioning and changelog management with git tags, pull request label
 
 :::{grid-item-card}
 :link: user-guide/ci-cd
-:link-type: doc
-:class-header: bg-light
 
 Automated CI/CD 🚀
 ^^^
@@ -67,8 +54,6 @@ Test, build, and publish your package to PyPi. Publish documentation to GitHub P
 
 :::{grid-item-card}
 :link: references/further-reading
-:link-type: doc
-:class-header: bg-light
 
 Further Reading 📖
 ^^^
@@ -82,4 +67,4 @@ This documentation is organized into a few major sections:
 
 - **Getting Started** provides an overview of the project and how to set it up.
 - **User Guide** contains details on how to use the template and the tools it provides.
-- **Reference** section includes further reading, besides [API references](references/api-reference.rst) and [How to Contribute](references/how-to-contribute.md) guides that are ready to be used by any project built with this template.
+- **Reference** section includes further reading, besides [API references](references/api-reference.md) and [How to Contribute](references/how-to-contribute.md) guides that are ready to be used by any project built with this template.
diff --git a/docs/myst.yml b/docs/myst.yml
@@ -0,0 +1,42 @@
+version: 1
+project:
+  title: The Wizard Template for Python Projects
+  authors:
+    - name: Felipe N. Schuch
+  copyright: '2023-2026'
+  github: fschuch/wizard-template
+  exports:
+    - format: pdf
+      template: plain_latex_book
+      output: exports/book.pdf
+  toc:
+    - file: intro.md
+    - title: Getting Started
+      children:
+        - file: getting-started/about.md
+        - file: getting-started/dependencies.md
+        - file: getting-started/use-this-template.md
+    - title: User Guide
+      children:
+        - file: user-guide/tooling/index.md
+          children:
+            - file: user-guide/tooling/pre-commit.md
+            - file: user-guide/tooling/mypy.md
+            - file: user-guide/tooling/ruff.md
+            - file: user-guide/tooling/codespell.md
+            - file: user-guide/tooling/pytest.md
+            - file: user-guide/tooling/zizmor.md
+        - file: user-guide/documentation.md
+        - file: user-guide/versioning-changelog.md
+        - file: user-guide/ci-cd.md
+    - title: References
+      children:
+        - file: references/further-reading.md
+        - file: references/api-reference.md
+        - file: references/how-to-contribute.md
+        - file: references/what-is-new.md
+site:
+  options:
+    logo: logo.png
+    folders: true
+  template: book-theme
diff --git a/docs/references/api-reference.md b/docs/references/api-reference.md
@@ -0,0 +1,11 @@
+# API Reference
+
+:::{note}
+This section provides the API reference for the `wizard_template` package.
+:::
+
+## Core Module
+
+The core module contains the main functionality of the wizard template.
+
+For detailed API documentation, please refer to the source code in `src/wizard_template/core.py`.
diff --git a/docs/references/api-reference.rst b/docs/references/api-reference.rst
diff --git a/docs/references/what-is-new.md b/docs/references/what-is-new.md
@@ -1,10 +1,7 @@
 # What's New
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Intended Effort Versioning](https://jacobtomlinson.dev/effver/) (EffVer for short).
-Release notes are automatically recovered from GitHub by [sphinx-github-changelog](https://github.com/ewjoachim/sphinx-github-changelog).
 
-```{changelog}
-:changelog-url: https://docs.fschuch.com/wizard-template/references/what-is-new.html
-:github: https://github.com/fschuch/wizard-template/releases/
-:pypi: https://pypi.org/project/wizard-template/
-```
+:::{note}
+Release notes are available on [GitHub Releases](https://github.com/fschuch/wizard-template/releases/) and [PyPI](https://pypi.org/project/wizard-template/).
+:::
diff --git a/pyproject.toml b/pyproject.toml
@@ -33,16 +33,12 @@ tests = [
     "pytest>=8.2.2",
 ]
 tests-extra = [
-    "pytest-randomly==3.16.0",
-    "pytest-rerunfailures==15.1",
+    "pytest-randomly==4.0.1",
+    "pytest-rerunfailures==16.1",
     "pytest-xdist==3.8.0",
 ]
 docs = [
-    "docutils==0.21.2",
-    "jupyter-book==1.0.4.post1",
-    "sphinx-autobuild==2024.10.3",
-    "sphinx==7.4.7",
-    "sphinx-github-changelog==1.7.1",
+    "jupyter-book==2.1.2",
 ]
 
 [project.urls]
@@ -133,9 +129,5 @@ installer = "uv"
 python = "3.12"
 
 [tool.hatch.envs.docs.scripts]
-config = "jupyter-book config sphinx docs {args}"
-build = ["config", "jupyter-book build docs --path-output build {args}"]
-serve = [
-    "config",
-    "sphinx-autobuild docs build/_build/html --open-browser --watch src/wizard_template {args}",
-]
+build = "jupyter-book build docs --path-output build {args}"
+serve = "jupyter-book start docs {args}"