jupyter · jasongrout · Nov 7, 2025 · Nov 7, 2025
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -30,13 +30,13 @@ jobs:
         pip install -r requirements.txt
 
 
-    # Build the book
-    - name: Build the book
+    # Build the site
+    - name: Build the MyST site
       run: |
-        jupyter-book build .
+        cd docs && myst build --html
 
     # Upload artifact
     - uses: actions/upload-artifact@v4
       with:
         name: html_docs
-        path: ./_build/html
+        path: ./docs/_build/html
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -36,14 +36,26 @@ jobs:
       run: |
         pip install -r requirements.txt
 
-    # Build the book
-    - name: Build the book
+    # Build the site
+    - name: Build the MyST site
+      env:
+        BASE_URL: /${{ github.event.repository.name }}
       run: |
-        jupyter-book build .
+        cd docs && myst build --html
+
+    # Generate redirects from old URLs to new URLs
+    - name: Generate redirects
+      run: |
+        python scripts/generate_redirects.py "https://jupyter.org/governance/" "docs/_build/redirects"
+
+    # Copy redirects into the build directory
+    - name: Merge redirects into build
+      run: |
+        cp -r docs/_build/redirects/* docs/_build/html/
 
     # Push the book's HTML to github-pages
     - name: GitHub Pages action
       uses: peaceiris/[email protected]
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./_build/html
+        publish_dir: ./docs/_build/html
diff --git a/README.md b/README.md
@@ -9,19 +9,24 @@ See [the governance introduction](intro.md) for license information.
 ## Infrastructure for this repository
 
 The content in this repository is hosted online with `github-pages`, and the HTML
-files are built with [jupyter-book](https://jupyterbook.org). To build and preview
-these documents locally, install the latest version of Jupyter Book with:
+files are built with [MyST](https://mystmd.org). To build and preview
+these documents locally, you can use [nox](https://nox.thea.codes):
 
-```
-pip install -U jupyter-book
+```bash
+# Build the documentation
+nox -s docs
+
+# Or serve with live reload
+nox -s docs-live
 ```
 
-and build the book with:
+Alternatively, install MyST directly and build manually:
 
-```
-cd path/to/this/repo
-jupyter-book build .
+```bash
+pip install -r requirements.txt
+cd docs
+myst build --html
 ```
 
-The resulting website will be in `_build/html`, which you can explore by opening
+The resulting website will be in `docs/_build/html`, which you can explore by opening
 any of the `.html` files that are created.
diff --git a/_config.yml b/_config.yml
diff --git a/_plausible.py b/_plausible.py
diff --git a/_toc.yml b/_toc.yml
diff --git a/archive/governance.md → docs/archive/governance.md b/archive/governance.md → docs/archive/governance.md
diff --git a/bootstrapping_executive_council.md → docs/bootstrapping_executive_council.md b/bootstrapping_executive_council.md → docs/bootstrapping_executive_council.md
diff --git a/bootstrapping_subproject_councils.md → docs/bootstrapping_subproject_councils.md b/bootstrapping_subproject_councils.md → docs/bootstrapping_subproject_councils.md
diff --git a/charters/DeiCharter.md → docs/charters/DeiCharter.md b/charters/DeiCharter.md → docs/charters/DeiCharter.md
diff --git a/charters/DocumentationCharter.md → docs/charters/DocumentationCharter.md b/charters/DocumentationCharter.md → docs/charters/DocumentationCharter.md
diff --git a/charters/MediaStrategyCharter.md → docs/charters/MediaStrategyCharter.md b/charters/MediaStrategyCharter.md → docs/charters/MediaStrategyCharter.md
diff --git a/communitybuildingworkinggroup.md → docs/communitybuildingworkinggroup.md b/communitybuildingworkinggroup.md → docs/communitybuildingworkinggroup.md
diff --git a/conduct/code_of_conduct.md → docs/conduct/code_of_conduct.md b/conduct/code_of_conduct.md → docs/conduct/code_of_conduct.md
@@ -122,6 +122,7 @@ by e-mailing
 [*[email protected]*](mailto:[email protected])
 within 24 hours.
 
+(reporting)=
 ## Reporting
 
 If you believe someone is violating the code of conduct, please report this in

diff --git a/conduct/enforcement.md → docs/conduct/enforcement.md b/conduct/enforcement.md → docs/conduct/enforcement.md
diff --git a/conduct/faq.md → docs/conduct/faq.md b/conduct/faq.md → docs/conduct/faq.md
diff --git a/conduct/reporting_events.md → docs/conduct/reporting_events.md b/conduct/reporting_events.md → docs/conduct/reporting_events.md
diff --git a/conduct/reporting_online.md → docs/conduct/reporting_online.md b/conduct/reporting_online.md → docs/conduct/reporting_online.md
diff --git a/decision_making.md → docs/decision_making.md b/decision_making.md → docs/decision_making.md
diff --git a/distinguished_contributors.md → docs/distinguished_contributors.md b/distinguished_contributors.md → docs/distinguished_contributors.md
diff --git a/elections/.gitignore → docs/elections/.gitignore b/elections/.gitignore → docs/elections/.gitignore
diff --git a/elections/LICENSE.md → docs/elections/LICENSE.md b/elections/LICENSE.md → docs/elections/LICENSE.md
diff --git a/elections/README.md → docs/elections/README.md b/elections/README.md → docs/elections/README.md
diff --git a/elections/process-votes.py → docs/elections/process-votes.py b/elections/process-votes.py → docs/elections/process-votes.py
diff --git a/elections/votes.csv → docs/elections/votes.csv b/elections/votes.csv → docs/elections/votes.csv
diff --git a/executive_council.md → docs/executive_council.md b/executive_council.md → docs/executive_council.md
diff --git a/intro.md → docs/intro.md b/intro.md → docs/intro.md
diff --git a/jupyter_foundation.md → docs/jupyter_foundation.md b/jupyter_foundation.md → docs/jupyter_foundation.md
diff --git a/...articipation_agreement_draft-20240702.pdf → ...articipation_agreement_draft-20240702.pdf b/...articipation_agreement_draft-20240702.pdf → ...articipation_agreement_draft-20240702.pdf
diff --git a/linux-proposal.md → docs/linux-proposal.md b/linux-proposal.md → docs/linux-proposal.md
diff --git a/...standing_committees_and_working_groups.md → ...standing_committees_and_working_groups.md b/...standing_committees_and_working_groups.md → ...standing_committees_and_working_groups.md
diff --git a/list_of_subprojects.md → docs/list_of_subprojects.md b/list_of_subprojects.md → docs/list_of_subprojects.md
diff --git a/docs/myst.yml b/docs/myst.yml
@@ -0,0 +1,70 @@
+version: 1
+project:
+  title: Project Jupyter Governance
+  copyright: ""
+  github: https://github.com/jupyter/governance
+  license: CC0-1.0
+  exclude:
+    - LICENSE.md
+    - README.md
+    - .github
+
+  toc:
+    - file: intro.md
+      title: Introduction
+
+    # Governance Section
+    - title: Governance
+      children:
+        - file: overview.md
+        - file: executive_council.md
+        - file: software_steering_council.md
+        - file: jupyter_foundation.md
+        - file: software_subprojects.md
+          children:
+            - file: list_of_subprojects.md
+            - file: newsubprojects.md
+        - file: standing_committees_and_working_groups.md
+          children:
+            - file: list_of_standing_committees_and_working_groups.md
+            - file: communitybuildingworkinggroup.md
+        - file: distinguished_contributors.md
+        - file: people.md
+
+    # Code of Conduct Section
+    - title: Code of Conduct
+      children:
+        - file: conduct/code_of_conduct.md
+          children:
+            - file: conduct/enforcement.md
+            - file: conduct/reporting_online.md
+            - file: conduct/reporting_events.md
+        - file: conduct/faq.md
+
+    # Organizational Policy Section
+    - title: Organizational Policy
+      children:
+        - file: decision_making.md
+        - file: papers.md
+        - file: trademarks.md
+        - file: projectlicense.md
+
+    # Previous Governance Section
+    - title: Archive
+      children:
+        - file: linux-proposal.md
+          title: Linux Foundation Proposal
+        - file: archive/governance.md
+          title: Previous Governance
+          children:
+            - file: bootstrapping_subproject_councils.md
+            - file: bootstrapping_executive_council.md
+
+site:
+  template: book-theme
+  title: Project Jupyter Governance
+  options:
+    logo_text: Project Jupyter
+  actions:
+    - title: Edit on GitHub
+      url: https://github.com/jupyter/governance/edit/main/docs
diff --git a/newsubprojects.md → docs/newsubprojects.md b/newsubprojects.md → docs/newsubprojects.md
@@ -58,6 +58,7 @@ official capacity?
 The two paths for official Subproject creation are now detailed.
 
 
+(direct-subproject-creation)=
 ## Direct Subproject creation
 
 In some cases, Steering Council members can immediately create new official Subprojects in the main
@@ -72,6 +73,7 @@ The process is completed when the Executive Council approves a PR that adds the
 [^example]: [Here's an example PR](https://github.com/jupyter/governance/pull/229) from the jupyter-book incorporation process.
 
 
+(incorporation-of-an-existing-external-subproject)=
 ## Incorporation of an existing external Subproject
 
 In other cases, Subprojects proposed for incorporation will have existed and been developed as

diff --git a/overview.md → docs/overview.md b/overview.md → docs/overview.md
@@ -33,7 +33,7 @@ For more details, see the [Standing Committees and Working Groups document](stan
 ### Union of Councils
 
 The Union of Councils represents the combination of councils, sub-councils, and working groups in Jupyter.
-See [](#union-of-councils) for more information.
+See [the Union of Councils section](#union-of-councils) for more information.
 
 
 ### Distinguished Contributors

diff --git a/papers.md → docs/papers.md b/papers.md → docs/papers.md