### Install NPM Dependencies and Start Development Server

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Install necessary Node.js packages and start the development server to watch for style changes.

```bash
npm install && npm start
```

--------------------------------

### Install Python Requirements

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Install all Python dependencies required for building the documentation.

```bash
pip install -r requirements.txt
```

--------------------------------

### Clone KoboToolbox Docs Repository

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Clone the repository to your local machine to begin setup.

```bash
git clone https://github.com/kobotoolbox/docs.git
```

--------------------------------

### Install NPM Dependencies for Theme Development

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Install Node.js packages required for custom theme development.

```bash
npm install
```

--------------------------------

### Example: Filtering Q2 based on Q1 Selections

Source: https://github.com/kobotoolbox/docs/blob/master/locales/es/choice_filters_xls.md

This example demonstrates how to set up the survey and choices worksheets so that Q2 only displays items previously selected in Q1.

```XLSForm
selected(${Q1}, name)
```

--------------------------------

### v1 Metadata Response Example

Source: https://github.com/kobotoolbox/docs/blob/master/source/migrating_api.md

This is an example of the JSON response structure for the v1 metadata endpoint.

```default
{
  "id": 271,
  "xform": 374,
  "data_value": "goose.jpg",
  "data_type": "media",
  "data_file": "/project_owner/form-media/b44a7c2cd0f244e6b405821582364657/goose.jpg",
  "data_file_type": "image/jpeg",
  "file_hash": "md5:93fb96bced1e3b392abfc22934afe51a",
  "url": "https://kc.kobotoolbox.org/api/v1/metadata/271?format=json",
  "from_kpi": true,
  "data_filename": "goose.jpg"
}
```

--------------------------------

### v2 Metadata Response Example

Source: https://github.com/kobotoolbox/docs/blob/master/source/migrating_api.md

This is an example of the equivalent JSON response structure for the v2 metadata endpoint, showing changes in field names and structure.

```default
{
  "uid": "afoeCcF3AcGNpWUoM6bvKj9",
  "asset": "http://kf.kobo.localhost/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "file_type": "form_media",
  "content": "http://kf.kobo.localhost/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/files/afoeCcF3AcGNpWUoM6bvKj9/content/",
  "metadata": {
    "hash": "md5:93fb96bced1e3b392abfc22934afe51a",
    "filename": "goose.jpg",
    "mimetype": "image/jpeg"
  },
  ...
}
```

--------------------------------

### v2 Form Endpoint Response Example

Source: https://github.com/kobotoolbox/docs/blob/master/source/migrating_api.md

This is an example of a response from the v2 API for asset data, equivalent to the v1 form endpoint. It includes pagination and different field names.

```json
{
  "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "owner__username": "project_owner",
  "files": [],
  "summary": {
    "geo": false
  },
  "version__content_hash": "05be1113c6ae66665059fea5943ce90a97d966db",
  "deployment__active": true,
  "deployment__submission_count": 1200,
  "deployment__last_submission_time": "2025-06-03T15:16:20.838131Z",
  "deployment__encrypted": false,
  "deployment__uuid": "f739945244514a6bb304dc35d6049880",
  "tag_string": "my_tag,my_other_tag",
  "uid": "a4etXeWtqcoodSxLV8a6Uq",
  "name": "Pathways Initiative",
  "permissions": [
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pQnggGHaPGGmJtPCbCCVpU/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/add_submissions/",
      "label": "Add submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pcn2g8ezroevNsP7CuCkrf/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/add_submissions/",
      "label": "Add submissions"
    }
  ]
}
```

--------------------------------

### XLSForm Survey and Choices Worksheets Example

Source: https://github.com/kobotoolbox/docs/blob/master/source/choice_filters_xls.md

Example demonstrating how to set up survey and choices worksheets in XLSForm to implement choice filtering. The 'Q2' question filters its choices based on the selections made in 'Q1'.

```XLSForm
type,name,label,choice_filter
select_multiple item,Q1,Which household items do you currently own?,
select_multiple item,Q2,Which of these items would you consider upgrading in the future?,selected(${Q1}, name)
survey,,

list_name,name,label
item,fridge,Refrigerator
item,tv,Television
item,fan,Ceiling fan
item,microwave,Microwave oven
item,radio,Radio
item,bike,Bicycle
item,phone,Mobile phone
item,laptop,Laptop computer
choices,,
```

--------------------------------

### XLSForm Survey Worksheet Example

Source: https://github.com/kobotoolbox/docs/blob/master/locales/fr/required_logic_xls.md

Demonstrates how to set up the survey worksheet with a 'required' column to enforce conditional logic for questions.

```xls
type	name	label	required
select_one yn	recontact	Do you agree to be contacted again for another study in the future?	
text	email	What is your email address?	${recontact} = ‘yes’
survey			
```

--------------------------------

### Basic select_one_from_file setup in XLSForm

Source: https://github.com/kobotoolbox/docs/blob/master/locales/es/select_from_file_xls.md

Use this configuration in the survey worksheet to link a select_one_from_file question to an external CSV file. Ensure the file name is correctly specified.

```XLSForm
type | name | label
select_one_from_file households.csv | hh | Select household
```

--------------------------------

### Example of using max() in survey worksheet

Source: https://github.com/kobotoolbox/docs/blob/master/source/repeat_groups_xls.md

This example shows a complete setup in the survey worksheet where a repeat group 'children' is defined, and a calculate question 'max_age' uses the max() formula to find the oldest child's age. The result is then used in a subsequent acknowledge question.

```xls
type	name	label	calculation
begin_repeat	children	Children roster	
text	name	Name	
select_one gender	gender	Gender	
integer	age	Age	
end_repeat			
calculate	max_age		max(${age})
acknowledge	confirm_age	Confirm that the oldest child in the household is **${max_age}** years old.	
```

--------------------------------

### Build HTML Documentation

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Generate the HTML files for the documentation site.

```bash
make html
```

--------------------------------

### Conditional check using regex

Source: https://github.com/kobotoolbox/docs/blob/master/locales/es/calculations_xls.md

Creates a binary variable based on whether a string matches a regular expression pattern. This example checks if an ID starts with 'ML-'.

```XLSForm
if(regex(${id}, '^ML-'), 'yes', 'no')
```

--------------------------------

### Navigate to KoboToolbox Docs Directory

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Change into the cloned repository directory to access project files.

```bash
cd docs
```

--------------------------------

### XLSForm Choices Worksheet for Dynamic Filtering

Source: https://github.com/kobotoolbox/docs/blob/master/locales/fr/choice_filters_xls.md

This example demonstrates the choices worksheet setup for dynamic filtering. It includes the parent list ('continent') and the child list ('country'), with a 'continent' column in the child list mapping choices to the parent list's names.

```xlsform
list_name	name	label	continent
continent	africa	Africa	
continent	asia	Asia	
country	malawi	Malawi	africa
country	zambia	Zambia	africa
country	india	India	asia
country	pakistan	Pakistan	asia
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Create a virtual environment for the project and activate it to manage dependencies.

```bash
python -m venv koboenv
source koboenv/bin/activate
```

--------------------------------

### Open Local Documentation

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Open the generated index page in your web browser to view the documentation locally.

```bash
open _build/html/index.html
```

--------------------------------

### Build Translated Documentation (Arabic)

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Build the documentation specifically for the Arabic language.

```bash
sphinx-build -b html locales/ar _build/html/ar
```

--------------------------------

### v1 Form Endpoint Response Example

Source: https://github.com/kobotoolbox/docs/blob/master/source/migrating_api.md

This is an example of a response from the v1 API for form data. It includes various attributes of a form.

```json
{
  "url": "https://kf.kobotoolbox.org/api/v1/forms/474",
  "formid": 474,
  "metadata": [],
  "owner": "project_owner",
  "public": false,
  "public_data": false,
  "require_auth": true,
  "tags": ["my_tag", "my_other_tag"],
  "title": "Pathways Initiative",
  "users": [
    {
      "user": "project_owner",
      "permissions": [
        "add_xform",
        "change_xform",
        "delete_data_xform",
        "delete_xform",
        "move_xform",
        "report_xform",
        "transfer_xform",
        "validate_xform",
        "view_xform"
      ]
    }
  ],
  "hash": "md5:65ee54b6412379b0e35b27a97d606c29",
  "downloadable": true,
  "encrypted": false,
  "id_string": "a4etXeWtqcoodSxLV8a6Uq",
  "last_submission_time": "2025-06-03T15:16:20.838131Z",
  "uuid": "f739945244514a6bb304dc35d6049880",
  "instances_with_geopoints": false,
  "num_of_submissions": 1200,
  "attachment_storage_bytes": 27240767883
}
```

--------------------------------

### Build Translated Documentation (Spanish)

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Build the documentation specifically for the Spanish language.

```bash
sphinx-build -b html locales/es _build/html/es
```

--------------------------------

### List Project Permissions (API v2)

Source: https://context7.com/kobotoolbox/docs/llms.txt

Use the KoboToolbox API v2 to list current permission assignments for a project. Requires authentication with a token and the server URL.

```bash
# List current permission assignments for a project
curl -H "Authorization: Token $TOKEN" \
  "$SERVER/api/v2/assets/$ASSET_UID/permission-assignments/"
```

--------------------------------

### Build Translated Documentation (French)

Source: https://github.com/kobotoolbox/docs/blob/master/README.md

Build the documentation specifically for the French language.

```bash
sphinx-build -b html locales/fr _build/html/fr
```

--------------------------------

### XLSForm Constraint Examples in Survey Worksheet

Source: https://github.com/kobotoolbox/docs/blob/master/locales/es/constraints_xls.md

Define constraints directly in the survey worksheet to enforce data quality rules. These examples show age and weight validation.

```XLSForm
. < 18 or . > 65
```

```XLSForm
. >= 30 and . <= 200
```

--------------------------------

### Basic Select from File Setup in XLSForm

Source: https://github.com/kobotoolbox/docs/blob/master/locales/fr/select_from_file_xls.md

Use `select_one_from_file` or `select_multiple_from_file` in the type column, followed by a space and the external file name (e.g., `households.csv`). This links the question to its choice list in the specified file.

```XLSForm
type | name   | label            
select_one_from_file households.csv | hh     | Select household 
survey                              |        |                  
```

--------------------------------

### XLSForm Choices Sheet Example

Source: https://github.com/kobotoolbox/docs/blob/master/locales/fr/xlsform_with_kobotoolbox.md

Example of a choices sheet in XLSForm format. Ensure 'name' values are unique within each 'list_name' to avoid errors. This structure is crucial for select_one and select_multiple questions.

```XLSForm
list_name | name | label
yn | yes | Yes, always
yn | yes | Yes, sometimes
yn | no | No, never
choices |  | 
```

--------------------------------

### List All Projects (Assets)

Source: https://context7.com/kobotoolbox/docs/llms.txt

Fetch a paginated list of all survey projects accessible to the authenticated user. Projects are identified by a unique `uid`.

```bash
# List all survey projects
curl -H "Authorization: Token $TOKEN" \
  "$SERVER/api/v2/assets/?asset_type=survey"

# Expected response
# {
#   "count": 5,
#   "next": null,
#   "previous": null,
#   "results": [
#     {
#       "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
#       "uid": "a4etXeWtqcoodSxLV8a6Uq",
#       "name": "Pathways Initiative",
#       "deployment__submission_count": 1200,
#       "deployment__active": true,
#       "deployment__last_submission_time": "2025-06-03T15:16:20.838131Z",
#       "data": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/data/"
#     }
#   ]
# }

# Store project UID for use in subsequent requests
ASSET_UID="a4etXeWtqcoodSxLV8a6Uq"
```

--------------------------------

### Basic Select One From File Setup in XLSForm

Source: https://github.com/kobotoolbox/docs/blob/master/source/select_from_file_xls.md

Use `select_one_from_file` in the `type` column, followed by a space and the external CSV file name, to link a single-choice question to an external list.

```xlsform
type                                | name   | label            |
select_one_from_file households.csv | hh     | Select household |
```

--------------------------------

### Advanced XLSForm Constraint Examples

Source: https://github.com/kobotoolbox/docs/blob/master/locales/es/constraints_xls.md

Utilize parentheses, functions, and regular expressions for more complex data validation scenarios. These examples cover range checks, conditional logic, select multiple, date validation, and numeric restrictions.

```XLSForm
(. >= 18 and . < 130) or (. = 999)
```

```XLSForm
not(${in_university} = ‘yes’ and . < 16)
```

```XLSForm
not(selected(., ‘none’) and count-selected(.)>1)
```

```XLSForm
. < today()
```

```XLSForm
regex(., ‘^\d{2}$’)
```

```XLSForm
decimal-time(.)>=0.5
```

--------------------------------

### Format Integer Constraint

Source: https://github.com/kobotoolbox/docs/blob/master/locales/ar/constraints_xls.md

Example of an integer constraint using a greater than operator.

```XLSForm
. > 35
```

--------------------------------

### Extract substring

Source: https://github.com/kobotoolbox/docs/blob/master/locales/es/calculations_xls.md

Extracts a portion of a string, specified by a starting position and length.

```XLSForm
substr(${question}, 1, 2)
```

--------------------------------

### Help Icon

Source: https://github.com/kobotoolbox/docs/blob/master/source/article_template.md

Use this HTML to display the general help icon.

```html
<i class="k-icon k-icon-help"></i>
```

--------------------------------

### Dynamic Data Attachments - Child Project Setup

Source: https://context7.com/kobotoolbox/docs/llms.txt

Configures a child project to pull live data from a parent project. This enables longitudinal data management by linking data collection efforts.

```APIDOC
# Step 1 — Parent project: enable data sharing
# In parent project: SETTINGS > Connect Projects > toggle Data Sharing ON

# Step 2 — Child XLSForm: declare the external data source
# survey worksheet
# ─────────────────────────────────────────────────────────────────────────────────────────────────
# type          | name           | label                          | calculation
# ──────────────┼────────────────┼────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────
# xml-external  | parent         |                                | 
# text          | participant_id | Enter the participant ID       | 
# calculate     | enrolled_age   |                                | instance('parent')/root/data[enrollment_id = current()/../participant_id]/age
# calculate     | enrolled_site  |                                | instance('parent')/root/data[enrollment_id = current()/../participant_id]/site
# integer       | followup_age   | Confirm participant age        | instance('parent')/root/data[enrollment_id = current()/../participant_id]/age
# note          | show_site      | Enrolled site: ${enrolled_site}| 
# end survey    |                |                                | 

# Step 3 — Link the child project to the parent in KoboToolbox UI:
# Child project: SETTINGS > Connect Projects > select parent project name
```