CogStack · alhendrickson · Feb 27, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026
diff --git a/medcat-trainer/.readthedocs.yaml b/medcat-trainer/.readthedocs.yaml
@@ -5,13 +5,19 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: "ubuntu-24.04"
   tools:
-    python: "3.9"
+    python: "3.13"
+  jobs:
+    pre_create_environment:
+        - cd medcat-trainer/docs
+        - asdf plugin add uv
+        - asdf install uv latest
+        - asdf global uv latest
+    create_environment:
+        - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+        - cd medcat-trainer/docs && UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen
 
-sphinx:
-  configuration: medcat-trainer/docs/conf.py
-
-python:
-  install:
-    - requirements: medcat-trainer/docs/requirements.txt
+mkdocs:
+  configuration: medcat-trainer/mkdocs.yml
diff --git a/medcat-trainer/docs/Makefile b/medcat-trainer/docs/Makefile
diff --git a/medcat-trainer/docs/annotator_guide.md b/medcat-trainer/docs/annotator_guide.md
@@ -71,6 +71,9 @@ The sidebar shows details for the currently selected concept, including:
 
 If enabled by project settings, a **Comment** field is also available.
 
+!!! tip
+    If the details are not showing in the sidebar after you've selected one, the issue is likely with an unfinished Project setup. See the section for "Concept lookup index (Solr import)" in the [Project Creation and Management Guide](project_admin.md) for details.
+
 ## Meta annotations and relations
 
 Depending on project configuration:

diff --git a/medcat-trainer/docs/conf.py b/medcat-trainer/docs/conf.py
diff --git a/medcat-trainer/docs/demo_page.md b/medcat-trainer/docs/demo_page.md
@@ -17,8 +17,8 @@ It does **not** persist annotation decisions like a project workflow does.
 
 1. Select a **Model Pack**.
 2. Optionally add CUI filters:
-   - pick concepts from the concept picker, or
-   - paste a comma-separated CUI list.
+    - pick concepts from the concept picker, or
+    - paste a comma-separated CUI list.
 3. Optionally enable **Include sub-concepts**.
 4. Enter or paste free text.
 

diff --git a/medcat-trainer/docs/main.md → medcat-trainer/docs/index.md b/medcat-trainer/docs/main.md → medcat-trainer/docs/index.md
@@ -1,4 +1,4 @@
-# Medical <img src="_static/img/cat-logo.png" width=45>oncept Annotation Tool Trainer
+# Medical <img src="_static/img/cat-logo.svg" width="45" alt="C">oncept Annotation Tool Trainer
 
 MedCATtrainer is a web application for creating, validating, and improving
 MedCAT concept annotation models on biomedical or clinical text.
@@ -10,15 +10,15 @@ review-only workflows (collect annotations without changing the model).
 
 - Build annotation projects from CSV/XLSX datasets.
 - Use either:
-  - a **Model Pack** (recommended), or
-  - a **Concept DB + Vocabulary** pair.
+    - a **Model Pack** (recommended), or
+    - a **Concept DB + Vocabulary** pair.
 - Optionally use a **remote MedCAT model service** for document preparation.
 - Collect concept-level labels:
-  - Correct
-  - Incorrect
-  - Alternative concept
-  - Terminate
-  - Irrelevant
+    - Correct
+    - Incorrect
+    - Alternative concept
+    - Terminate
+    - Irrelevant
 - Collect optional **meta annotations** and **relation annotations**.
 - Use **Project Groups** for multi-annotator setups.
 - Run **metrics reports** across one or more compatible projects.
@@ -27,9 +27,9 @@ review-only workflows (collect annotations without changing the model).
 ## Typical workflow
 
 1. Install and configure MedCATtrainer.
-2. Create users and upload model artifacts (Model Pack or CDB/Vocab).
-3. Create a project and assign annotators.
-4. Annotate and submit documents.
+2. Create users and upload model artifacts (Model Pack or CDB/Vocab). [Administrator Setup](admin_setup.md)
+3. Create a project and assign annotators. [Annotation Project Creation and Management](project_admin.md)
+4. Annotate and submit documents. [Annotator Guide](annotator_guide.md)
 5. Export annotations and evaluate with the metrics tools.
 
 ## Documentation map

diff --git a/medcat-trainer/docs/index.rst b/medcat-trainer/docs/index.rst
diff --git a/medcat-trainer/docs/installation.md b/medcat-trainer/docs/installation.md
@@ -1,5 +1,13 @@
 # Installation
 
+The steps to setup Medcat trainer are as follows:
+
+1. Run MedCAT Trainer with Docker or Helm
+2. Setup the Administrator user with [Administrator Setup](admin_setup.md) 
+3. Configure annotations Projects
+
+This page details the initial running of the application with Docker
+
 MedCATtrainer is packaged as a Docker Compose deployment with three core
 services:
 
@@ -61,6 +69,7 @@ Host-level Compose variables (for example port overrides) can be set by copying
 
 | Variable | Description |
 |---|---|
+| `CSRF_TRUSTED_ORIGINS` | Allowed origins to access the admin panel. Mandatory to set if you expose the app over a different URL or port (default `'http://127.0.0.1:8001', 'http://localhost:8001'`). |
 | `MCTRAINER_PORT` | Host port for the web UI/API (default `8001`). |
 | `SOLR_PORT` | Host port for Solr admin (default `8983`). |
 | `MEDCAT_CONFIG_FILE` | MedCAT config file path inside the container. |
@@ -129,3 +138,6 @@ An example compose file is available at
   startup logs.
 - **Concept picker empty**: confirm Solr is running and concepts were imported
   for the selected CDB.
+
+## Next Steps
+Now that medcat trainer is installed and running, proceed to [Administrator Setup](admin_setup.md) to create the Admin user.
diff --git a/medcat-trainer/docs/maintenance.md b/medcat-trainer/docs/maintenance.md
@@ -36,8 +36,8 @@ The backup scripts are SQLite-focused (`DB_ENGINE=sqlite3`).
 - A backup is taken on startup before migrations.
 - A scheduled backup job also runs regularly.
 - Backup location is controlled by:
-  - `DB_PATH`
-  - `DB_BACKUP_DIR`
+    - `DB_PATH`
+    - `DB_BACKUP_DIR`
 
 ### Restore process
 

diff --git a/medcat-trainer/docs/make.bat b/medcat-trainer/docs/make.bat
diff --git a/medcat-trainer/docs/meta_annotations.md b/medcat-trainer/docs/meta_annotations.md
@@ -16,11 +16,11 @@ Create and manage tasks in Django admin (`/admin`):
 
 1. Create **Meta Task Values** (the allowed label options).
 2. Create a **Meta Task**:
-   - name
-   - values
-   - default value (optional)
-   - description
-   - ordering
+    - name
+    - values
+    - default value (optional)
+    - description
+    - ordering
 3. Attach selected tasks to your project (`Project annotate entities`).
 
 ## Model-pack predictions vs manual labels

diff --git a/medcat-trainer/docs/project_admin.md b/medcat-trainer/docs/project_admin.md
@@ -10,11 +10,11 @@ MedCATtrainer supports two management surfaces:
 1. Open `/project-admin`.
 2. Go to the **Projects** tab and select **Create New Project**.
 3. Fill in:
-   - **Basic information** (name, dataset, description, guideline link)
-   - **Model configuration**
-   - **Annotation settings**
-   - **Concept filter (optional)**
-   - **Members**
+    - **Basic information** (name, dataset, description, guideline link)
+    - **Model configuration**
+    - **Annotation settings**
+    - **Concept filter (optional)**
+    - **Members**
 4. Save.
 
 ### Model configuration options

diff --git a/medcat-trainer/docs/pyproject.toml b/medcat-trainer/docs/pyproject.toml
@@ -0,0 +1,19 @@
+[project]
+name = "medcat-trainer-documentation"
+version = "0.1.0"
+description = "MedCAT Trainer Documentation"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mkdocs-material>=9.7.0",
+    "termynal>=0.13.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.12.11",
+]
+
+[tool.ruff]
+line-length = 120
+
diff --git a/medcat-trainer/docs/requirements.txt b/medcat-trainer/docs/requirements.txt