From 18662e6a64f06169fc93dd48b62472c69e461f1c Mon Sep 17 00:00:00 2001
From: Aykhan Shahsuvarov <aykhan.shahs@gmail.com>
Date: Sat, 17 Jan 2026 21:18:37 +0400
Subject: [PATCH] Add file upload examples and fix templating.md table of
 contents

---
 docs/examples.md   | 64 +++++++++++++++++++++++++++++++++++++++++-----
 docs/templating.md |  9 ++++---
 2 files changed, 62 insertions(+), 11 deletions(-)

diff --git a/docs/examples.md b/docs/examples.md
index a4065e0..060adf5 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -521,7 +521,7 @@ body: '{{ body_FormData "title" "My Document" "document" "@/path/to/file.pdf" }}
 
 </details>
 
-**Multiple file uploads:**
+**Multiple file uploads (same field name):**
 
 ```sh
 sarin -U http://example.com/api/upload -r 100 -c 10 \
@@ -538,10 +538,36 @@ requests: 100
 concurrency: 10
 method: POST
 body: |
-  {{ body_FormData
-     "files" "@/path/to/file1.pdf"
-     "files" "@/path/to/file2.pdf"
-  }}
+    {{ body_FormData
+       "files" "@/path/to/file1.pdf"
+       "files" "@/path/to/file2.pdf"
+    }}
+```
+
+</details>
+
+**Multiple file uploads (different field names):**
+
+```sh
+sarin -U http://example.com/api/upload -r 100 -c 10 \
+  -M POST \
+  -B '{{ body_FormData "avatar" "@/path/to/photo.jpg" "resume" "@/path/to/cv.pdf" "cover_letter" "@/path/to/letter.docx" }}'
+```
+
+<details>
+<summary>YAML equivalent</summary>
+
+```yaml
+url: http://example.com/api/upload
+requests: 100
+concurrency: 10
+method: POST
+body: |
+    {{ body_FormData
+       "avatar" "@/path/to/photo.jpg"
+       "resume" "@/path/to/cv.pdf"
+       "cover_letter" "@/path/to/letter.docx"
+    }}
 ```
 
 </details>
@@ -569,7 +595,7 @@ body: '{{ body_FormData "image" "@https://example.com/photo.jpg" }}'
 
 > **Note:** Files (local and remote) are cached in memory after the first read, so they are not re-read for every request.
 
-**Base64 encoded file in JSON body:**
+**Base64 encoded file in JSON body (local file):**
 
 ```sh
 sarin -U http://example.com/api/upload -r 100 -c 10 \
@@ -587,12 +613,36 @@ requests: 100
 concurrency: 10
 method: POST
 headers:
-  Content-Type: application/json
+    Content-Type: application/json
 body: '{"file": "{{ file_Base64 "/path/to/file.pdf" }}", "filename": "document.pdf"}'
 ```
 
 </details>
 
+**Base64 encoded file in JSON body (remote URL):**
+
+```sh
+sarin -U http://example.com/api/upload -r 100 -c 10 \
+  -M POST \
+  -H "Content-Type: application/json" \
+  -B '{"image": "{{ file_Base64 "https://example.com/photo.jpg" }}", "filename": "photo.jpg"}'
+```
+
+<details>
+<summary>YAML equivalent</summary>
+
+```yaml
+url: http://example.com/api/upload
+requests: 100
+concurrency: 10
+method: POST
+headers:
+    Content-Type: application/json
+body: '{"image": "{{ file_Base64 "https://example.com/photo.jpg" }}", "filename": "photo.jpg"}'
+```
+
+</details>
+
 ## Using Proxies
 
 **Single HTTP proxy:**
diff --git a/docs/templating.md b/docs/templating.md
index 3fddd05..4ff3e49 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -11,6 +11,7 @@ Sarin supports Go templates in URL paths, methods, bodies, headers, params, cook
     - [String Functions](#string-functions)
     - [Collection Functions](#collection-functions)
     - [Body Functions](#body-functions)
+    - [File Functions](#file-functions)
 - [Fake Data Functions](#fake-data-functions)
     - [File](#file)
     - [ID](#id)
@@ -110,8 +111,8 @@ sarin -U http://example.com/users \
 
 ### Body Functions
 
-| Function                       | Description                                                              | Example                                          |
-| ------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------ |
+| Function                         | Description                                                                                                                                                                                                 | Example                                                             |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
 | `body_FormData(pairs ...string)` | Create multipart form data from key-value pairs. Automatically sets the `Content-Type` header. Values starting with `@` are treated as file references (local path or URL). Use `@@` to escape literal `@`. | `{{ body_FormData "field1" "value1" "file" "@/path/to/file.pdf" }}` |
 
 **`body_FormData` Details:**
@@ -150,8 +151,8 @@ body: '{{ body_FormData "twitter" "@@username" }}'
 
 ### File Functions
 
-| Function                    | Description                                                                 | Example                                    |
-| --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |
+| Function                     | Description                                                                                               | Example                                 |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------- |
 | `file_Base64(source string)` | Read a file (local path or URL) and return its Base64 encoded content. Files are cached after first read. | `{{ file_Base64 "/path/to/file.pdf" }}` |
 
 **`file_Base64` Details:**