diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
new file mode 100644
index 00000000..6e8fea8b
--- /dev/null
+++ b/.github/workflows/docs.yaml
@@ -0,0 +1,60 @@
+name: Deploy Jupyter Book
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yaml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Jupyter Book 2.0 and MyST
+        run: |
+          uv pip install --pre "jupyter-book==2.*" --system
+          npm install -g mystmd
+
+      - name: Build book
+        run: |
+          cd docs
+          rm -rf _build .jupyter_cache
+          myst clean || true
+          myst build --html
+          touch _build/html/.nojekyll
+        env:
+          BASE_URL: /policyengine-uk-data
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: docs/_build/html
+          clean: true
\ No newline at end of file
diff --git a/changelog_entry.yaml b/changelog_entry.yaml
index e69de29b..dbb4c3b0 100644
--- a/changelog_entry.yaml
+++ b/changelog_entry.yaml
@@ -0,0 +1,6 @@
+- bump: minor
+  changes:
+    changed:
+    - Upgraded documentation to Jupyter Book 2.0 (MyST-based)
+    fixed:
+    - Jupyter Book deployment to GitHub Pages by adding docs workflow and fixing branch reference
\ No newline at end of file
diff --git a/docs/_config.yml b/docs/_config.yml
deleted file mode 100644
index 39d74982..00000000
--- a/docs/_config.yml
+++ /dev/null
@@ -1,24 +0,0 @@
-title: PolicyEngine UK data
-author: PolicyEngine
-copyright: "2024"
-logo: logo.png
-
-execute:
-  execute_notebooks: force
-  allow_errors: false
-  timeout: 600
-
-repository:
-  url: https://github.com/policyengine/policyengine-uk-data
-  branch: master
-  path_to_book: docs
-
-sphinx:
-  config:
-    html_js_files:
-    - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.7/require.min.js
-    html_theme: furo
-    pygments_style: default
-    html_css_files:
-      - style.css
-    nb_remove_code_source: true
\ No newline at end of file
diff --git a/docs/_toc.yml b/docs/_toc.yml
deleted file mode 100644
index 2e7dd86b..00000000
--- a/docs/_toc.yml
+++ /dev/null
@@ -1,12 +0,0 @@
-format: jb-book
-root: intro
-chapters:
-- file: methodology.ipynb
-- file: validation/index.md
-  sections:
-  - file: validation/national.ipynb
-  - file: validation/constituencies.ipynb
-  - file: validation/local_authorities.ipynb
-- file: pension_contributions.ipynb
-- file: constituency_methodology.ipynb
-- file: LA_methodology.ipynb
\ No newline at end of file
diff --git a/docs/myst.yml b/docs/myst.yml
new file mode 100644
index 00000000..165211b4
--- /dev/null
+++ b/docs/myst.yml
@@ -0,0 +1,25 @@
+version: 1
+project:
+  title: PolicyEngine UK data
+  authors:
+    - name:
+        given: PolicyEngine
+        family: Team
+  copyright: '2024'
+  github: policyengine/policyengine-uk-data
+  toc:
+    - file: intro.md
+    - file: methodology.ipynb
+    - file: validation/index.md
+      children:
+        - file: validation/national.ipynb
+        - file: validation/constituencies.ipynb
+        - file: validation/local_authorities.ipynb
+    - file: pension_contributions.ipynb
+    - file: constituency_methodology.ipynb
+    - file: LA_methodology.ipynb
+site:
+  options:
+    logo: logo.png
+    folders: true
+  template: book-theme