DeepLabCut · C-Achard · May 21, 2026 · May 21, 2026 · May 21, 2026 · May 21, 2026
diff --git a/.github/workflows/docs_and_notebooks_checks.yml b/.github/workflows/docs_and_notebooks_checks.yml
@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   staleness:
-    name: Docs and notebooks scan (read-only)
+    name: Docs and notebooks scan (changed docs only)
     runs-on: ubuntu-latest
     timeout-minutes: 5
 
@@ -31,29 +31,75 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install "pydantic>=2,<3" pyyaml "nbformat>=5"
 
+      - name: Collect changed .md/.ipynb files
+        id: changed_docs
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p tmp/docs_nb_checks
+
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            base="${{ github.event.pull_request.base.sha }}"
+            head="${{ github.event.pull_request.head.sha }}"
+          else
+            base="${{ github.event.before }}"
+            head="${{ github.sha }}"
+          fi
+
+          git diff --name-only --diff-filter=ACMR "$base" "$head" \
+          | { grep -iE '\.(md|ipynb)$' || true; } \
+          | { grep -E '^(docs/|tools/|examples/COLAB/|examples/JUPYTER/)' || true; } \
+          | sort -u > tmp/docs_nb_checks/changed_docs.txt
+
+          count=$(wc -l < tmp/docs_nb_checks/changed_docs.txt | tr -d ' ')
+          echo "count=$count" >> "$GITHUB_OUTPUT"
+
+          echo "Changed docs files:"
+          if [[ "$count" -eq 0 ]]; then
+            echo "(none)"
+          else
+            sed 's/^/- /' tmp/docs_nb_checks/changed_docs.txt
+          fi
+
       - name: Run staleness report (read-only)
+        if: steps.changed_docs.outputs.count != '0'
+        shell: bash
         run: |
-          python tools/docs_and_notebooks_check.py \
-          --config tools/docs_and_notebooks_report_config.yml \
-          --out-dir tmp/docs_nb_checks \
-          report
+          set -euo pipefail
+          mapfile -t targets < tmp/docs_nb_checks/changed_docs.txt
 
+          python tools/docs_and_notebooks_check.py \
+            --config tools/docs_and_notebooks_report_config.yml \
+            --out-dir tmp/docs_nb_checks \
+            report \
+            --targets "${targets[@]}"
 
-      # Optional: run check mode (will fail only once you populate allowlists in config)
       - name: Run staleness policy check (optional gate)
+        if: steps.changed_docs.outputs.count != '0'
         continue-on-error: true
+        shell: bash
         run: |
+          set -euo pipefail
+          mapfile -t targets < tmp/docs_nb_checks/changed_docs.txt
+
           python tools/docs_and_notebooks_check.py \
-          --config tools/docs_and_notebooks_report_config.yml \
-          --out-dir tmp/docs_nb_checks \
-          --no-step-summary \
-          check
+            --config tools/docs_and_notebooks_report_config.yml \
+            --out-dir tmp/docs_nb_checks \
+            --no-step-summary \
+            check \
+            --targets "${targets[@]}"
+
+      - name: No changed docs to scan
+        if: steps.changed_docs.outputs.count == '0'
+        run: echo "No changed .md or .ipynb files found in the repo. Skipping scan."
 
       - name: Upload staleness artifacts
+        if: steps.changed_docs.outputs.count != '0'
         uses: actions/upload-artifact@v4
         with:
           name: staleness-report
           path: |
             tmp/docs_nb_checks/*.json
             tmp/docs_nb_checks/*.md
+            tmp/docs_nb_checks/changed_docs.txt
           if-no-files-found: error
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -84,6 +84,15 @@ repos:
         args: [--check, --diff]
         stages: [manual]
 
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-myst
+        files: ^docs/.*\.md$
+        stages: [pre-commit]
+
   # check only, no modifications
   - repo: local
     hooks:
@@ -93,6 +102,7 @@ repos:
         language: python
         pass_filenames: true
         files: ^(docs/|examples/(JUPYTER|COLAB)/|tools/).*(\.md|\.ipynb)$
+        exclude: ^tools/docs_audits/
         args:
           - --config
           - tools/docs_and_notebooks_report_config.yml

diff --git a/README.md b/README.md
diff --git a/_toc.yml b/_toc.yml
@@ -2,125 +2,117 @@ format: jb-book
 root: README
 
 parts:
-- caption: Getting Started
-  chapters:
-  - file: docs/UseOverviewGuide
-  - file: docs/course
-
-- caption: Installation
-  chapters:
-  - file: docs/installation
-  - file: docs/recipes/installTips
-  - file: docs/docker
-
-- caption: Main User Guides
-  chapters:
-  - file: docs/standardDeepLabCut_UserGuide
-  - file: docs/maDLC_UserGuide
-  - file: docs/Overviewof3D
-  - file: docs/HelperFunctions
-
-- caption: Graphical User Interfaces (GUIs)
-  chapters:
-  - file: docs/gui/PROJECT_GUI
-  - file: docs/gui/napari_GUI
-    sections:
-      - file: docs/gui/napari/basic_usage
-      - file: docs/gui/napari/advanced_usage
-
-- caption: DLC3 PyTorch Specific Docs
-  chapters:
-  - file: docs/pytorch/user_guide.md
-  - file: docs/pytorch/pytorch_config.md
-  - file: docs/pytorch/architectures.md
-
-- caption: Quick Start Tutorials
-  chapters:
-  - file: docs/quick-start/single_animal_quick_guide
-  - file: docs/quick-start/tutorial_maDLC
-
-- caption: "🚀 Beginner's Guide to DeepLabCut"
-  chapters:
-  - file: docs/beginner-guides/beginners-guide
-  - file: docs/beginner-guides/manage-project
-  - file: docs/beginner-guides/labeling
-  - file: docs/beginner-guides/Training-Evaluation
-  - file: docs/beginner-guides/video-analysis
-
-- caption: "🚀 Main Demo Notebooks"
-  chapters:
-  - file: examples/COLAB/COLAB_DEMO_SuperAnimal
-  - file: examples/COLAB/COLAB_DEMO_mouse_openfield
-  - file: examples/COLAB/COLAB_3miceDemo
-  - file: examples/COLAB/COLAB_HumanPose_with_RTMPose
-
-- caption: "🚀 Notebooks For Your Data"
-  chapters:
-  - file: examples/COLAB/COLAB_YOURDATA_SuperAnimal
-  - file: examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis
-  - file: examples/COLAB/COLAB_YOURDATA_maDLC_TrainNetwork_VideoAnalysis
-
-- caption: "🚀 Special Feature Demos"
-  chapters:
-  - file: examples/COLAB/COLAB_transformer_reID
-  - file: examples/COLAB/COLAB_BUCTD_and_CTD_tracking
-  - file: examples/JUPYTER/Demo_3D_DeepLabCut
-  - file: examples/COLAB/COLAB_DLC_ModelZoo
-
-- caption: "🧑‍🍳 Cookbook (detailed helper guides)"
-  chapters:
-  - file: docs/convert_maDLC
-  - file: docs/recipes/OtherData
-  - file: docs/recipes/io
-  - file: docs/recipes/nn
-  - file: docs/recipes/post
-  - file: docs/recipes/BatchProcessing
-  - file: docs/recipes/DLCMethods
-  - file: docs/recipes/ClusteringNapari
-  - file: docs/recipes/OpenVINO
-  - file: docs/recipes/flip_and_rotate
-  - file: docs/recipes/pose_cfg_file_breakdown
-  - file: docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook
-
-- caption: Hardware Tips
-  chapters:
-  - file: docs/recipes/TechHardware
-
-- caption: DeepLabCut-Live!
-  chapters:
-  - file: docs/dlc-live/deeplabcutlive
-  - file: docs/dlc-live/dlc-live-gui/index
-    sections:
-      - file: docs/dlc-live/dlc-live-gui/quickstart/install
-      - file: docs/dlc-live/dlc-live-gui/user_guide/overview
-      - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support
+  - caption: Getting started
+    chapters:
+      - file: docs/UseOverviewGuide
+      - file: docs/installation
         sections:
-          - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/opencv_backend
-          - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/basler_backend
-          - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/aravis_backend
-          - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/gentl_backend
-      - file: docs/dlc-live/dlc-live-gui/user_guide/misc/misc_landing
+          # - file: docs/recipes/installTips
+          - file: docs/docker
+      # - file: docs/quick-start/index
+        # sections:
+          # - file: docs/quick-start/single_animal_quick_guide
+          # - file: docs/quick-start/tutorial_maDLC
+
+  - caption: Main workflows overview
+    chapters:
+      - file: docs/standardDeepLabCut_UserGuide
+      - file: docs/maDLC_UserGuide
+      - file: docs/Overviewof3D
+
+  - caption: GUI workflow
+    chapters:
+      - file: docs/gui/PROJECT_GUI
         sections:
-          - file: docs/dlc-live/dlc-live-gui/user_guide/misc/modelzoo_downloads
-          - file: docs/dlc-live/dlc-live-gui/user_guide/misc/timestamp_format
-
-- caption: "🦄 DeepLabCut Model Zoo"
-  chapters:
-  - file: docs/ModelZoo
-  - file: docs/recipes/UsingModelZooPupil
-
-- caption: DeepLabCut Benchmarking
-  chapters:
-  - file: docs/benchmark
-  - file: docs/pytorch/Benchmarking_shuffle_guide
-
-- caption: "Mission & Contribute"
-  chapters:
-  - file: docs/MISSION_AND_VALUES
-  - file: docs/roadmap
-  - file: docs/Governance
-  - file: CONTRIBUTING
+          - file: docs/beginner-guides/beginners-guide
+          - file: docs/beginner-guides/manage-project
+          - file: docs/beginner-guides/labeling
+          - file: docs/beginner-guides/Training-Evaluation
+          - file: docs/beginner-guides/video-analysis
+      - file: docs/gui/napari_GUI
+        sections:
+          - file: docs/gui/napari/basic_usage
+          - file: docs/gui/napari/advanced_usage
+          - file: docs/gui/napari/tracking/basic_usage
 
-- caption: Citations for DeepLabCut
-  chapters:
-    - file: docs/citation
+  - caption: Notebooks & Demos
+    chapters:
+      - file: docs/notebooks/your_data
+        sections:
+          - file: examples/COLAB/COLAB_YOURDATA_SuperAnimal
+          - file: examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis
+          - file: examples/COLAB/COLAB_YOURDATA_maDLC_TrainNetwork_VideoAnalysis
+      - file: docs/notebooks/main_demos
+        sections:
+          - file: examples/COLAB/COLAB_DEMO_SuperAnimal
+          - file: examples/COLAB/COLAB_DEMO_mouse_openfield
+          - file: examples/COLAB/COLAB_3miceDemo
+          - file: examples/COLAB/COLAB_HumanPose_with_RTMPose
+      - file: docs/notebooks/extra
+        sections:
+          - file: examples/COLAB/COLAB_transformer_reID
+          - file: examples/COLAB/COLAB_BUCTD_and_CTD_tracking
+          - file: examples/JUPYTER/Demo_3D_DeepLabCut
+          - file: examples/COLAB/COLAB_DLC_ModelZoo
+
+  - caption: DeepLabCut 3.0 - PyTorch guides
+    chapters:
+      - file: docs/pytorch/index
+        sections:
+          - file: docs/pytorch/user_guide.md
+          - file: docs/pytorch/pytorch_config.md
+          - file: docs/pytorch/architectures.md
+          - file: docs/pytorch/Benchmarking_shuffle_guide
+
+  - caption: Advanced, Performance & Live
+    chapters:
+      - file: docs/ModelZoo
+        sections:
+          - file: docs/recipes/UsingModelZooPupil
+      - file: docs/dlc-live/deeplabcutlive
+      - file: docs/dlc-live/dlc-live-gui/index
+        sections:
+          - file: docs/dlc-live/dlc-live-gui/quickstart/install
+          - file: docs/dlc-live/dlc-live-gui/user_guide/overview
+          - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support
+            sections:
+              - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/opencv_backend
+              - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/basler_backend
+              - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/aravis_backend
+              - file: docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/gentl_backend
+          - file: docs/dlc-live/dlc-live-gui/user_guide/misc/misc_landing
+            sections:
+              - file: docs/dlc-live/dlc-live-gui/user_guide/misc/modelzoo_downloads
+              - file: docs/dlc-live/dlc-live-gui/user_guide/misc/timestamp_format
+      - file: docs/benchmark
+      - file: docs/recipes/TechHardware
+
+  - caption: Additional guides (Recipes)
+    chapters:
+      - file: docs/recipes/index
+        sections:
+          - file: docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook
+          - file: docs/HelperFunctions
+          - file: docs/convert_maDLC
+          - file: docs/recipes/OtherData
+          - file: docs/recipes/io
+          - file: docs/recipes/nn
+          - file: docs/recipes/post
+          - file: docs/recipes/BatchProcessing
+          - file: docs/recipes/DLCMethods
+          - file: docs/recipes/ClusteringNapari
+          - file: docs/recipes/OpenVINO
+          - file: docs/recipes/flip_and_rotate
+          - file: docs/recipes/pose_cfg_file_breakdown
+          # - file: docs/course
+      - file: docs/dlc-utils/index
+        sections:
+          - file: docs/dlc-utils/XROMM/usage
+
+  - caption: Project & Community
+    chapters:
+      - file: docs/MISSION_AND_VALUES
+      - file: docs/roadmap
+      - file: docs/Governance
+      - file: CONTRIBUTING
+      - file: docs/citation
diff --git a/docs/Governance.md b/docs/Governance.md
@@ -4,8 +4,11 @@ deeplabcut:
   last_metadata_updated: '2026-03-06'
   ignore: false
 ---
+
 (governance-model)=
+
 # Governance Model of DeepLabCut
+
 (adapted from https://napari.org/stable/community/governance.html)
 
 ## Abstract
@@ -112,7 +115,7 @@ DeepLabCut uses a “consensus seeking” process for making decisions. The grou
 tries to find a resolution that has no open objections among core developers.
 Core developers are expected to distinguish between fundamental objections to a
 proposal and minor perceived flaws that they can live with, and not hold up the
-decision-making process for the latter.  If no option can be found without
+decision-making process for the latter. If no option can be found without
 objections, the decision is escalated to the SC, which will itself use
 consensus seeking to come to a resolution. In the unlikely event that there is
 still a deadlock, the proposal will move forward if it has the support of a
@@ -139,7 +142,7 @@ are made according to the following rules:
   decision-making process outlined above.
 
 - **Changes to this governance model or our mission, vision, and values**
-  require a  dedicated issue on our [issue tracker](https://github.com/DeepLabCut/DeepLabCut/issues)
+  require a dedicated issue on our [issue tracker](https://github.com/DeepLabCut/DeepLabCut/issues)
   and follow the decision-making process outlined above,
   *unless* there is unanimous agreement from core developers on the change in
   which case it can move forward faster.