DeepLabCut · deruyter92 · May 27, 2026 · May 29, 2026 · May 29, 2026 · May 19, 2026
diff --git a/_toc.yml b/_toc.yml
@@ -11,13 +11,16 @@ parts:
           - 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/main-workflows/user-guide
+        sections:
+          - file: docs/quick-start/single_animal_quick_guide
+          - file: docs/quick-start/tutorial_maDLC
+          - file: docs/main-workflows/multi-animal-tracking
+      # - file: docs/standardDeepLabCut_UserGuide
+      # - file: docs/maDLC_UserGuide
       - file: docs/Overviewof3D
 
   - caption: GUI workflow

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -9,6 +9,17 @@ html[data-theme="light"] {
   --logo-filter: none;
   --button-color: #fff;
   --footer-text-color: #000000;
+
+  /* Workflow dropdown/admonition colors */
+  --single-animal-border: #9b5de5;
+  --single-animal-bg: #f5edff;
+  --single-animal-title-bg: #ead7ff;
+  --single-animal-title-text: #4b236f;
+
+  --multi-animal-border: #57c4be;
+  --multi-animal-bg: #e8f8f7;
+  --multi-animal-title-bg: #21a197;
+  --multi-animal-title-text: #000000;
 }
 
 html[data-theme="dark"] {
@@ -20,6 +31,17 @@ html[data-theme="dark"] {
   /* --logo-filter: grayscale(100%) brightness(20); */
   --button-color: #fff;
   --footer-text-color: #b9b9b9;
+
+  /* Workflow dropdown/admonition colors */
+  --single-animal-border: #c084fc;
+  --single-animal-bg: rgba(72, 86, 107, 0.16);
+  --single-animal-title-bg: rgba(241, 83, 255, 0.32);
+  --single-animal-title-text: #f3e8ff;
+
+  --multi-animal-border: #57c4be;
+  --multi-animal-bg: rgba(72, 86, 107, 0.16);
+  --multi-animal-title-bg: #21a197;
+  --multi-animal-title-text: #000000;
 }
 
 /* Sidebar */
@@ -101,3 +123,257 @@ html[data-theme="dark"] {
   opacity: 0.8;
   z-index: 1;
 }
+
+/* ============================================================
+   Workflow-specific dropdown/admonition styling
+   Single animal = light purple
+   Multi animal  = light green
+
+   Recommended MyST usage:
+
+   ```{dropdown}
+   :class-container: single-animal
+   :open:
+
+   Single-animal-specific instructions.
+   ```
+
+   ```{dropdown}
+   :class-container: multi-animal
+   :open:
+
+   Multi-animal-specific instructions.
+   ```
+   ============================================================ */
+
+/* ------------------------------------------------------------
+   Sphinx-design dropdowns
+   Usually rendered with .sd-dropdown
+   ------------------------------------------------------------ */
+
+.sd-dropdown.single-animal {
+  border-left: 0.35rem solid var(--single-animal-border);
+  background-color: var(--single-animal-bg);
+  border-radius: 0.5rem;
+  margin: 1rem 0;
+  overflow: hidden;
+}
+
+.sd-dropdown.single-animal>.sd-summary-title {
+  background-color: var(--single-animal-title-bg);
+  color: var(--single-animal-title-text);
+  font-weight: 700;
+}
+
+.sd-dropdown.multi-animal {
+  border-left: 0.35rem solid var(--multi-animal-border);
+  background-color: var(--multi-animal-bg);
+  border-radius: 0.5rem;
+  margin: 1rem 0;
+  overflow: hidden;
+}
+
+.sd-dropdown.multi-animal>.sd-summary-title {
+  background-color: var(--multi-animal-title-bg);
+  color: var(--multi-animal-title-text);
+  font-weight: 700;
+}
+
+/* ------------------------------------------------------------
+   Regular Sphinx/MyST admonitions as fallback
+
+   ```{admonition} Configuration
+   :class: single-animal
+
+   Single-animal-specific instructions.
+   ```
+   ------------------------------------------------------------ */
+
+div.admonition.single-animal {
+  border-left: 0.35rem solid var(--single-animal-border);
+  background-color: var(--single-animal-bg);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+div.admonition.single-animal>.admonition-title {
+  background-color: var(--single-animal-title-bg);
+  color: var(--single-animal-title-text);
+  font-weight: 700;
+}
+
+div.admonition.multi-animal {
+  border-left: 0.35rem solid var(--multi-animal-border);
+  background-color: var(--multi-animal-bg);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+div.admonition.multi-animal>.admonition-title {
+  background-color: var(--multi-animal-title-bg);
+  color: var(--multi-animal-title-text);
+  font-weight: 700;
+}
+
+/* ------------------------------------------------------------
+   Raw HTML <details> fallback
+
+   <details class="workflow-dropdown single-animal" open>
+   <summary>Configuration</summary>
+
+   Single-animal-specific instructions.
+   </details>
+   ------------------------------------------------------------ */
+
+details.workflow-dropdown {
+  border: 1px solid transparent;
+  border-left-width: 0.35rem;
+  border-radius: 0.5rem;
+  margin: 1rem 0;
+  padding: 0;
+  overflow: hidden;
+}
+
+details.workflow-dropdown>summary {
+  cursor: pointer;
+  font-weight: 700;
+  padding: 0.6rem 0.9rem;
+  list-style-position: inside;
+}
+
+details.workflow-dropdown>*:not(summary) {
+  padding-left: 1rem;
+  padding-right: 1rem;
+}
+
+details.workflow-dropdown.single-animal {
+  border-left-color: var(--single-animal-border);
+  background-color: var(--single-animal-bg);
+}
+
+details.workflow-dropdown.single-animal>summary {
+  background-color: var(--single-animal-title-bg);
+  color: var(--single-animal-title-text);
+}
+
+details.workflow-dropdown.multi-animal {
+  border-left-color: var(--multi-animal-border);
+  background-color: var(--multi-animal-bg);
+}
+
+details.workflow-dropdown.multi-animal>summary {
+  background-color: var(--multi-animal-title-bg);
+  color: var(--multi-animal-title-text);
+}
+
+/* ------------------------------------------------------------
+   Compatibility fallback for dropdowns rendered as div.dropdown
+   ------------------------------------------------------------ */
+
+div.dropdown.single-animal {
+  border-left: 0.35rem solid var(--single-animal-border);
+  background-color: var(--single-animal-bg);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+div.dropdown.single-animal>.admonition-title,
+div.dropdown.single-animal>.sd-summary-title {
+  background-color: var(--single-animal-title-bg);
+  color: var(--single-animal-title-text);
+  font-weight: 700;
+}
+
+div.dropdown.multi-animal {
+  border-left: 0.35rem solid var(--multi-animal-border);
+  background-color: var(--multi-animal-bg);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+
+div.dropdown.multi-animal>.admonition-title,
+div.dropdown.multi-animal>.sd-summary-title {
+  background-color: var(--multi-animal-title-bg);
+  color: var(--multi-animal-title-text);
+  font-weight: 700;
+}
+
+/* ============================================================
+   Workflow dropdowns: title from CSS, default alignment,
+   custom left stripe, no hover color shift
+   ============================================================ */
+
+/* Hide sphinx-design's no-title kebab icon */
+details.sd-dropdown.sd-card.single-animal .sd-summary-text>svg.no-title,
+details.sd-dropdown.sd-card.multi-animal .sd-summary-text>svg.no-title {
+  display: none !important;
+}
+
+/* CSS-generated titles inside the default title span */
+details.sd-dropdown.sd-card.single-animal .sd-summary-text::before {
+  content: "🐁 Single animal";
+}
+
+details.sd-dropdown.sd-card.multi-animal .sd-summary-text::before {
+  content: "🐀🐀🐀 Multi animal";
+}
+
+/* Single animal colors */
+details.sd-dropdown.sd-card.single-animal>summary.sd-card-header {
+  --pst-sd-dropdown-color: var(--single-animal-border);
+  --pst-sd-dropdown-bg-color: var(--single-animal-title-bg);
+
+  color: var(--single-animal-title-text) !important;
+  background-color: var(--single-animal-title-bg) !important;
+}
+
+/* The body also needs the variable because pydata sets border-left there too */
+details.sd-dropdown.sd-card.single-animal>summary.sd-card-header+div.sd-summary-content {
+  --pst-sd-dropdown-color: var(--single-animal-border);
+
+  background-color: var(--single-animal-bg) !important;
+}
+
+/* Multi animal colors */
+details.sd-dropdown.sd-card.multi-animal>summary.sd-card-header {
+  --pst-sd-dropdown-color: var(--multi-animal-border);
+  --pst-sd-dropdown-bg-color: var(--multi-animal-title-bg);
+
+  color: var(--multi-animal-title-text) !important;
+  background-color: var(--multi-animal-title-bg) !important;
+}
+
+/* The body also needs the variable because pydata sets border-left there too */
+details.sd-dropdown.sd-card.multi-animal>summary.sd-card-header+div.sd-summary-content {
+  --pst-sd-dropdown-color: var(--multi-animal-border);
+
+  background-color: var(--multi-animal-bg) !important;
+}
+
+/* Keep text, emoji, chevron color stable */
+details.sd-dropdown.sd-card.single-animal .sd-summary-text,
+details.sd-dropdown.sd-card.single-animal .sd-summary-state-marker,
+details.sd-dropdown.sd-card.single-animal .sd-summary-state-marker svg {
+  color: var(--single-animal-title-text) !important;
+  fill: currentColor !important;
+}
+
+details.sd-dropdown.sd-card.multi-animal .sd-summary-text,
+details.sd-dropdown.sd-card.multi-animal .sd-summary-state-marker,
+details.sd-dropdown.sd-card.multi-animal .sd-summary-state-marker svg {
+  color: var(--multi-animal-title-text) !important;
+  fill: currentColor !important;
+}
+
+/* Disable pydata hover darken/lighten effect */
+details.sd-dropdown.sd-card.single-animal>summary.sd-card-header:hover,
+details.sd-dropdown.sd-card.single-animal>summary.sd-card-header:focus {
+  color: var(--single-animal-title-text) !important;
+  background-color: var(--single-animal-title-bg) !important;
+}
+
+details.sd-dropdown.sd-card.multi-animal>summary.sd-card-header:hover,
+details.sd-dropdown.sd-card.multi-animal>summary.sd-card-header:focus {
+  color: var(--multi-animal-title-text) !important;
+  background-color: var(--multi-animal-title-bg) !important;
+}
diff --git a/docs/images/box1-multi-rec.png b/docs/images/box1-multi-rec.png
diff --git a/docs/images/dlc-workflow.png b/docs/images/dlc-workflow.png
diff --git a/docs/installation.md b/docs/installation.md
@@ -319,13 +319,15 @@ Create a new conda environment with Python 3.10 (or 3.11, 3.12) by running:
 `conda create -n DLC python=3.10`
 
 **Current version:** The only thing you then need to add to the env is deeplabcut (
-`pip install deeplabcut`) or `pip install 'deeplabcut[gui]'` which has a napari based
-GUI.
+`pip install deeplabcut`) or `pip install 'deeplabcut[gui]'` if you are using the GUI, which includes the napari based labeling
+interface.
 
 ## Updating your installation
 
-If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` inside your env.
-If you want to use a specific release, then specify the version you want, such as `pip install deeplabcut==3.0`.
+If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` (alongside optional needed requirements, e.g. `[gui]`) using your environment.
+
+If you would like to use a specific release, then specify the version you want, such as `pip install deeplabcut==3.0` and optional requirements.
+
 Once installed, you can
 check the version by running: