From 68511edac648d552a53742b1f3745f07b1f7beb5 Mon Sep 17 00:00:00 2001
From: Mac <kevinmcaloonx@gmail.com>
Date: Mon, 5 Jan 2026 21:09:34 -0800
Subject: [PATCH] Add documentation for CSV task import and update related
 sections

---
 content/en/v1/user/import_tasks.md | 72 ++++++++++++++++++++++++++++++
 content/en/v1/user/tasks.md        |  8 ++++
 2 files changed, 80 insertions(+)
 create mode 100644 content/en/v1/user/import_tasks.md

diff --git a/content/en/v1/user/import_tasks.md b/content/en/v1/user/import_tasks.md
new file mode 100644
index 0000000..0cf8dda
--- /dev/null
+++ b/content/en/v1/user/import_tasks.md
@@ -0,0 +1,72 @@
+---
+title: "Importing Tasks via CSV"
+linktitle: "Import Tasks"
+---
+
+# Importing Tasks via CSV
+
+Kanboard supports importing tasks from CSV files. This guide explains the CSV format, the positional field semantics used by the importer, and provides a recommended template for reliable imports.
+
+## Overview
+
+The CSV importer in Kanboard uses **positional fields**, not header names.  
+This means the *order* of fields matters, and empty fields must be preserved to maintain alignment.
+
+A minimal, stable header for task imports is:
+
+reference,title,description,,,,column,,swimlane
+
+The commas represent positional fields that must remain present, even when empty.
+
+## Positional Field Reference
+
+Kanboard interprets each row using the following positional mapping:
+
+| Position | Meaning        | Notes |
+|---------|----------------|-------|
+| 1 | reference    | Optional identifier; can be anything |
+| 2 | title        | Required; task title |
+| 3 | description  | Optional; task description |
+| 4 | category     | Leave empty unless using Kanboard categories |
+| 5 | swimlane (ignored) | Fallback swimlane slot |
+| 6 | column (ignored)   | Fallback column slot |
+| 7 | column       | Primary column field; must match an existing board column |
+| 8 | color        | Leave empty unless using Kanboard color codes |
+| 9 | swimlane     | Primary swimlane field; must match an existing swimlane |
+
+### Importer rule
+
+Kanboard scans all fields left‑to‑right and assigns values based on pattern matching.  
+The **last valid match wins** for each attribute.
+
+Removing empty fields shifts the scan and changes how the importer interprets the row.
+
+## Recommended Template Data Example
+
+```csv
+reference,title,description,,,,column,,swimlane
+"task‑001","My task","Some description",,,,"Backlog",,"Your swimlane #1"
+"task‑002","Another task","Some other description",,,,"Done",,"Your swimlane #2"
+```
+
+## Usage
+
+1. Prepare a CSV file using the template above.  
+2. Ensure column and swimlane names match your board exactly.  
+3. Go to **Settings → Import Tasks**.  
+4. Click **Choose File**
+5. Click **Import** to upload the file and create your tasks.
+
+## Troubleshooting
+
+### Tasks appear in the wrong column or swimlane
+One or more empty fields were removed, shifting positional alignment.
+
+### Column or swimlane is ignored
+The value does not match an existing Kanboard column or swimlane.
+
+### Placeholder text disappears
+Kanboard discards values that do not match known entities.
+
+### Import succeeds but fields appear blank
+Unused positional fields are ignored unless populated with valid values.
diff --git a/content/en/v1/user/tasks.md b/content/en/v1/user/tasks.md
index 4f1eb3c..45f58b7 100644
--- a/content/en/v1/user/tasks.md
+++ b/content/en/v1/user/tasks.md
@@ -42,6 +42,14 @@ Then the task creation form appears:
 
 With the preview link, you can see the task description converted from Markdown syntax.
 
+Importing Tasks via CSV file
+----------------------------
+
+### Bulk load tasks into swimlanes
+
+Kanboard supports importing tasks from CSV files.  
+See [Importing Tasks via CSV](import_tasks.md) for details on the CSV format, field semantics, and templates.
+
 Duplicating and Moving Tasks
 ----------------------------