DeepLabCut · C-Achard · May 27, 2026 · Apr 15, 2026 · Apr 15, 2026 · Apr 15, 2026
diff --git a/README.md b/README.md
diff --git a/docs/README.md b/docs/README.md
@@ -4,6 +4,11 @@ deeplabcut:
   last_metadata_updated: '2026-03-06'
   ignore: false
 ---
+
+<!-- We currently use the root README.md for the main documentation -->
+
+<!-- It could be useful to use this one for metadata tracking, though GitHub will render the frontmatter metadata as plain text... -->
+
 Please see https://deeplabcut.github.io/DeepLabCut for documentation on how to use this software.
 
 This directory contains the source code for the docs.
diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md
diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md
@@ -6,19 +6,32 @@ deeplabcut:
   visibility: online
   status: viable
   recommendation: move
-  notes: "As mentioned on other beginner-guides/ docs, this should be part of the GUI section."
+  notes: As mentioned on other beginner-guides/ docs, this should be part of the GUI section.
 ---
-# Neural Network training and evaluation in the GUI
+
+(file:training-evaluation-gui)=
+
+# Neural network training and evaluation in the GUI
+
 <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1572296495650-Y4ZTJ2XP2Z9XF1AD74VW/ke17ZwdGBToddI8pDm48kMulEJPOrz9Y8HeI7oJuXxR7gQa3H78H3Y0txjaiv_0fDoOvxcdMmMKkDsyUqMSsMWxHk725yiiHCCLfrh8O1z5QPOohDIaIeljMHgDF5CVlOqpeNLcJ80NK65_fV7S1UZiU3J6AN9rgO1lHw9nGbkYQrCLTag1XBHRgOrY8YAdXW07ycm2Trb21kYhaLJjddA/DLC_logo_blk-01.png?format=1000w" width="150" title="DLC-live" alt="DLC LIVE!" align="right" vspace = "50">
 
+## Network training
+
+### Creating a training dataset
 
 Before training your model, the first step is to assemble your training dataset.
+This involves:
 
-**Create Training Dataset:** Move to the corresponding tab and click **`Create Training Dataset`**. For starters, the default settings will do just fine. While there are more powerful models and data augmentations you might want to consider, you can trust that for most projects the defaults are an ideal place to start.
+- Splitting labeled data into training and evaluation subsets
+- Creating each shuffle folder with the model configuration ready for training.
 
-> 💡 **Note:** This guide assumes you have a GPU on your local machine. If you're CPU-bound and finding training challenging, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started!
+**Create Training Dataset:** Move to the corresponding tab and click **`Create Training Dataset`**. For starters, the default settings will do just fine. While there are more powerful models and data augmentations you might want to consider, you can trust that for most projects the defaults are a good place to start.
 
-## Kickstarting the Training Process
+```{note}
+This guide assumes you have a (CUDA-enabled) GPU on your local machine. If you're CPU-bound and training is not feasible, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started!
+```
+
+### Starting the training process
 
 With your training dataset ready, it's time to train your model.
 
@@ -33,31 +46,34 @@ You can keep an eye on the training progress via your terminal window. This will
 
 ![DeepLabCut Training in Terminal with TF](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779598041-DC8UJA2NXJXG65ZWJH1O/training-terminal.png?format=500w)
 
-## Evaluate the Network
+## Network evaluation
 
 After training, it's time to see how well your model performs.
 
-### Steps to Evaluate the Network
+### Step-by-step
 
 1. Find and click on the **`Evaluate Network`** tab.
-2. **Choose Evaluation Options:**
+1. **Choose Evaluation Options:**
    - **Plot Predictions:** Select this to visualize the model's predictions, similar to standard DeepLabCut (DLC) evaluations.
    - **Compare Bodyparts:** Opt to compare all the bodyparts for a comprehensive evaluation.
-3. Click the **`Evaluate Network`** button, located on the right side of the main window.
-
->💡 Tip: If you wish to evaluate all saved snapshots, go to the configuration file and change the `snapshotindex` parameter to `all`.
+1. Click the **`Evaluate Network`** button, located on the right side of the main window.
 
+```{tip}
+If you wish to evaluate all saved snapshots, go to the configuration file and change the `snapshotindex` parameter to `all`.
+```
 
-### Understanding the Evaluation Results
+### Interpreting the results
 
 - **Performance Metrics:** DLC will assess the latest snapshot of your model, generating a `.CSV` file with performance
-metrics. This file is stored in the **`evaluation-results`** (for TensorFlow models) or the
-**`evaluation-results-pytorch`** (for PyTorch models) folder within your project.
+  metrics. This file is stored in the **`evaluation-results`** (for TensorFlow models) or the
+  **`evaluation-results-pytorch`** (for PyTorch models) folder within your project.
 
+![Combined Evaluation Results in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779617667-0RLTM9DVRALN9YIKSHJZ/combined-evaluation-results.png?format=750w)
 
-![Combined Evaluation Results in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779617667-0RLTM9DVRALN9YIKSHJZ/combined-evaluation-results.png?format=750w))
 - **Visual Feedback:** Additionally, DLC creates subfolders containing your frames overlaid with both the labeled bodyparts and the model's predictions, allowing you to visually gauge the network's performance.
 
-![Evaluation Example in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779623162-BFDAW37B9TO94EGME2O5/check-labels.png?format=500w))
+![Evaluation Example in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779623162-BFDAW37B9TO94EGME2O5/check-labels.png?format=500w)
+
+## Next steps
 
-## Next, head over the beginner guide for [using your new neural network for video analysis](video-analysis)
+Head over the {ref}`file:video-analysis-gui` section to learn about applying your trained model to videos, and creating labeled videos with the results of your analysis!
diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md
@@ -5,24 +5,32 @@ deeplabcut:
   ignore: false
   visibility: online
   status: outdated
-  recommendation: update
-  notes: "While it could seem like a useful page for beginners, duplicating installation instructions is not ideal for maintenance. This is also mixing installation/setup with a GUI guide, which should be in its own section/page. This puts into question the reason of existence of this page, as it would end up being two links to different sections. I would rather have well-made, accurate installation and GUI guides, and if there are beginner-relevant information that really cannot fit into those, then we can have a 'beginner's guide' that links to those and has the extra info. I would suggest reviewing whether this style of docs should remain at all, but if we want to keep them revising the approach may be needed."
+  recommendation: move
+  notes: Move to GUI section.
 ---
-(beginners-guide)=
-# Using DeepLabCut
+
+(file:beginners-guide)=
+
+# Using the DeepLabCut GUI
+
 <img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1572296495650-Y4ZTJ2XP2Z9XF1AD74VW/ke17ZwdGBToddI8pDm48kMulEJPOrz9Y8HeI7oJuXxR7gQa3H78H3Y0txjaiv_0fDoOvxcdMmMKkDsyUqMSsMWxHk725yiiHCCLfrh8O1z5QPOohDIaIeljMHgDF5CVlOqpeNLcJ80NK65_fV7S1UZiU3J6AN9rgO1lHw9nGbkYQrCLTag1XBHRgOrY8YAdXW07ycm2Trb21kYhaLJjddA/DLC_logo_blk-01.png?format=1000w" width="150" title="DLC-live" alt="DLC LIVE!" align="right" vspace = "50">
 
-This guide, and related pages, are meant as a very-new-to-python beginner guide to DeepLabCut. After you are comfortable with this material we recommend then jumping into the more detailed User Guides!
+This guide and the related pages are intended as a beginner-friendly introduction to DeepLabCut for users who are new to Python. After you are comfortable with this material, we recommend then jumping into the more detailed user guides!
+
+<!-- The course is outdated -->
 
-- **ProTip:** For even more 'in-depth' understanding, head over to check out the [DeepLabCut Course](https://deeplabcut.github.io/DeepLabCut/docs/course.html), which provides a deeper dive into the science behind DeepLabCut.
+<!-- - **ProTip:** For even more 'in-depth' understanding, head over to check out the [DeepLabCut Course](https://deeplabcut.github.io/DeepLabCut/docs/course.html), which provides a deeper dive into the science behind DeepLabCut. -->
 
 ## Installation
 
 Before you begin, make sure that DeepLabCut is installed on your system.
+Please see the {ref}`installation page<file:how-to-install>` for detailed instructions on how to install DeepLabCut on your computer.
 
-- **ProTip:** For detailed installation instructions, geared towards a bit more advanced users, refer to the [Full Installation Guide](https://deeplabcut.github.io/DeepLabCut/docs/installation.html).
+<!-- Avoid repeating installation instructions here -->
 
+<!--
 ## Beginner User Guide
+
 If you are new to Python, the best way to get Python installed onto your computer is with Anaconda. [Head over here and download the version that is best for your computer](https://www.anaconda.com/download).
 
 - "Conda", as it's often called, it a very nice way to create "environments (env)" on your computer. While there can be some cross-talk, in general, it allows you to separate the different tools you need to use to get your science done 💪.
@@ -38,22 +46,27 @@ In the terminal, type:
 ```
 conda create -n deeplabcut python=3.10
 ```
+
 You will be prompted (y/n) to install, and then wait for the magic to happen. At the end, check the terminal, it should prompt you to then type:
 
 ```
 conda activate deeplabcut
 ```
+
 Now, we are going to install the core dependencies. The way this works is that there are "package managers" such as `conda` itself and python's `pip`. We are going to deploy a mix based on what we know works across ooperating systems.
 
 **(1) Install PyTorch**
 
 `PyTorch` is the backend deep-learning language we wrote DLC3 in. To select the right version, head to the ["Install PyTorch"](https://pytorch.org/get-started/locally/) instructions in the official PyTorch Docs. Select your desired PyTorch build, operating system, select conda as your package manager and Python as the language. Select your compute platform (either a CUDA version or CPU only). Then, use the command to install the PyTorch package. Below are a few possible examples:
 
 - **GPU version of pytorch for CUDA 12.4**
+
 ```
 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
 ```
+
 - **CPU only version of pytorch, using the latest version**
+
 ```
 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
 ```
@@ -63,82 +76,123 @@ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
 Alright! Next, we will install all the `deeplabcut` source code 🔥. Please decide which version you want (stable or alpha), then type:
 
 - For the **Stable release:**
+
 ```
 pip install "deeplabcut[gui,modelzoo,wandb]"
 ```
+
 - This gives you DeepLabCut, the DLC GUI (gui), our latest neural networks (modelzoo) and a cool data logger (wandb) if you choose to use it later on!
 
 - OR for the **Alpha release (from GitHub bleeding edge of the code):**
+
 ```
 pip install "git+https://github.com/DeepLabCut/DeepLabCut.git@pytorch_dlc#egg=deeplabcut[gui,modelzoo,wandb]"
-```
+``` -->
 
-## Starting DeepLabCut
+## Starting the DeepLabCut GUI
+
+In the terminal, type:
 
-In the terminal, enter:
 ```bash
 python -m deeplabcut
 ```
-This will open the DeepLabCut App (note, the default is dark mode, but you can click "appearance" to change:
+
+This will open DeepLabCut.
+
+<!-- (note, the default is dark mode, but you can click "appearance" to change: -->
 
 ![DeepLabCut GUI Screenshot](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779625875-5UHPC367I293CBSP8CT6/GUI-screenshot.png?format=500w)
 
-> 💡 **Note:** For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4).
+```{note}
+For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4).
+```
 
-## Starting a New Project
+## Starting a new project
 
-### Navigating the GUI on Initial Launch
+### Navigating the GUI on initial Launch
 
 When you first launch the GUI, you'll find three primary main options:
 
 1. **Create New Project:** Geared towards new initiatives. A good choice if you're here to start something new.
-2. **Load Project:** Use this to resume your on-hold or past work.
-3. **Model Zoo:** Best suited for those who want to explore Model Zoo.
+1. **Load Project:** Use this to resume your on-hold or past work.
+1. **Model Zoo:** Best suited for those who want to explore Model Zoo.
 
-### Commencing Your Work:
+<!-- ### Creating a : -->
 
-- For a first-time or new user, please click on **`Start New Project`**.
+<!-- - For a first-time or new user, please click on **`Start New Project`**. -->
 
-## 🐾 Steps to Start a New Project
+### 🐾 New project step-by-step
 
 1. **Launch New Project:**
+
    - When you start a new project, you'll be presented with an empty project window. In DLC3+ you will see a new option "Engine".
-   - We recommend using the PyTorch Engine:
 
- ![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w))
+   ![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w)
+
+   ```{note}
+   For most users, the engine will be PyTorch. See {ref}`sec:deeplabcut-with-tf-install` for TensorFlow support.
+   ```
+
+1. **Filling in Project Details:**
 
-2. **Filling in Project Details:**
    - **Naming Your Project:**
-     - Give a specific, well-defined name to your project.
 
-      > **💡 Tip:** Avoid empty spaces in your project name.
+     - Give a specific, easy-to-track name to your project.
+
+     ```{tip}
+     Avoid spaces in your project name.
+     ```
+
+     - **Fill in the name of the scorer/experimenter**. This name is used in data headers and directory names and it remains permanently associated with the project.
 
-   - **Naming the Experimenter:**
-     - Fill in the name of the experimenter. This part of the data remains immutable.
+1. **Determine Project Location:**
 
-3. **Determine Project Location:**
    - By default, your project will be located on the **Desktop**.
-   - To pick a different home, modify the path as needed.
+   - To pick a different location, browse as needed.
 
-4. **Multi-Animal or Single-Animal Project:**
-   - Tick the 'Multi-Animal' option in the menu, but only if that's the mode of the project.
+1. **Multi-Animal or Single-Animal Project:**
+
+   - Tick the 'Multi-Animal' option in the menu if relevant to your experiment.
    - Choose the 'Number of Cameras' as per your experiment.
 
-5. **Adding Videos:**
+1. **Adding Videos:**
+
    - First, click on **`Browse Videos`** button on the right side of the window, to search for the video contents.
    - Once the media selection tool opens, navigate and select the folder with your videos.
-
-     > **💡 Tip:** DeepLabCut supports **`.mp4`**, **`.avi`**, **`.mkv`** and **`.mov`** files.
+     ```{tip}
+     DeepLabCut supports **`.mp4`**, **`.avi`**, **`.mkv`** and **`.mov`** files.
+     ```
    - A list will be created with all the videos inside this folder.
    - Unselect the videos you wish to remove from the project.
+   - Videos outside the project directory can be automatically copied into the project folder by selecting the "Copy videos to project folder" option. This is the recommended strategy for data management. External videos that are not copied are instead referenced via symbolic links. While using symbolic links avoids duplicating files and reduces storage usage, it is also more prone to issues, for example if the original files are moved or deleted.
+   - ```{tip}
+      By default, the GUI will look for a **directory** containing videos. Use the "Select individual files"
+      checkbox if you want to select individual videos instead of a whole folder.
+     ```
+
+1. **Define bodyparts and individuals:**
 
-6. **Create your project:**
-   - Click on **`Create`** button on the bottom, right side of the main window.
-   - A new folder named after your project's name will be created in the location you chose above.
+   - Enter all the name, numbers or IDs of bodyparts you wish to track.
+     - **Example:** "head", "tail", "left paw", "right paw", etc.
+     - Less recommended: "L1", "L2", "L3", etc.
+   - **If you have multiple animals**:
+     - Enter the name, numbers or IDs of the individuals in your experiment.
+       - **Example:** "mouse1", "mouse2", "mouse3", etc.
+     - **Unique bodyparts**: If you wish to track "landmark" locations, such as the edges of a maze, or a specific object, you can add these as "unique bodyparts". These are not considered part of an individual, but are still tracked as part of the project.
+       - **Example**: "maze_left_edge", "maze_right_edge", "reward_port", etc.
+     - **Identity labeling**: if and only if you can tell individuals apart by their appearance (not their location), set this to Yes and consistently label your individuals in the same way across videos. This will allow DeepLabCut to learn to tell them apart, and assign consistent identities across frames and videos.
 
+1. **Create your project:**
+
+   - Click on the **`Create`** button on the bottom, right side of the main window.
+   - A new folder will be created in the location you chose above.
+
+## Video tutorial
 
 ### 📽 Video Tutorial: Setting Up Your Project in DeepLabCut
 
 ![DeepLabCut Create Project GIF](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779616437-30U5RFYV0OY6ACGDG7F4/create-project.gif?format=500w)
 
-## Next, head over to the beginner guide for [Setting up what keypoints to track](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/manage-project.html)
+## Next steps
+
+Next, head over to the beginner guide for {ref}`editing the configuration and managing the project <file:manage-project-gui>`, which will show you how to edit the configuration file to edit your bodyparts and skeleton structure.