Update documentation

docs/widgets.md

@@ -1298,6 +1298,155 @@ In other words: Private, noncomercial, moderate use of the API is tolerated. The
 
 ---
 
+### Custom List
+
+Renders custom schema-compliant JOSN  in a list.
+
+#### Options
+**Field** | **Type** | **Required** | **Description**
+--- | --- | --- | ---
+**`url`** | `text` |  Required | A string containing the url of a json file.
+**`title`** | `text` |  optional | A title for the widget. Can be helpful if stacking multiple lists in the same section.
+**`daysForNew`** | `number` |  Optional | Used to highlight new items.
+
+#### Json Schema
+The input file should comply with the following schema:
+```json
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "array",
+  "items": [
+    {
+      "type": "object",
+      "properties": {
+        "link": {
+          "type": "object",
+          "properties": {
+            "text": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "text",
+            "url",
+            "title"
+          ]
+        },
+        "value": {
+          "type": "object",
+          "properties": {
+            "text": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "text",
+            "title"
+          ]
+        },
+        "date": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "link",
+        "value",
+        "date"
+      ]
+    }
+  ]
+}
+```
+
+Example: This json data was generated by a data worflow that gets the new releases of a few projects from GitHub. The system used to build the data workflow is n8n.
+
+```json
+[
+    {
+        "link": {
+            "text": "jellyfin/jellyfin",
+            "url": "https://github.com/jellyfin/jellyfin/releases/tag/v10.10.7",
+            "title": ""
+        },
+        "value": {
+            "text": "v10.10.7",
+            "title": "2025-04-05"
+        },
+        "date": "2025-04-05T19:14:59Z"
+    },
+    {
+        "link": {
+            "text": "jellyfin/jellyfin-web",
+            "url": "https://github.com/jellyfin/jellyfin-web/releases/tag/v10.10.7",
+            "title": ""
+        },
+        "value": {
+            "text": "v10.10.7",
+            "title": "2025-04-05"
+        },
+        "date": "2025-04-05T19:15:00Z"
+    },
+    {
+        "link": {
+            "text": "lissy93/dashy",
+            "url": "https://github.com/Lissy93/dashy/releases/tag/3.1.1",
+            "title": ""
+        },
+        "value": {
+            "text": "3.1.1",
+            "title": "2024-05-30"
+        },
+        "date": "2024-05-30T17:20:53Z"
+    },
+    {
+        "link": {
+            "text": "VSCodium/vscodium",
+            "url": "https://github.com/VSCodium/vscodium/releases/tag/1.102.14746",
+            "title": ""
+        },
+        "value": {
+            "text": "1.102.14746",
+            "title": "2025-07-16"
+        },
+        "date": "2025-07-16T18:27:49Z"
+    }
+]
+```
+#### Notes
+- This widget is designed to render data generated by another system that complies with the schema. The example JSON data above was generated using a n8n workflow, and other ETL or workflow systems can generate similar results.
+- To avoid requests to a different system in each refresh, you can save the input files locally in the user-data folder inside your Dashy installation.
+- To use json files from a different domain, remember to add `useProxy: true` to the widget configuration. I have not tested this use case because I save all my input data locally on the Dashy server. Please open a ticket if you have an issue in this use case.
+ 
+#### Example
+
+This widget renders a json file that from a `json-data` directory inside the `user-data` directory on the Dashy server.
+```yaml
+  - type: custom-list
+    options:
+      url: /json-data/github-releases.json
+      title: 'Github Releases'
+      daysForNew: 5
+```
+
+#### Info
+
+- **CORS**: 🟢 Not needed for files hosted inside the `user-data` directory. Use `useProxy: true` to bypass CORS restrictions when using data from a different server.
+- **Auth**: 🟢 Not Required
+- **Price**: 🟢 Free 
+- **Host**: user defined
+- **Privacy**: depends on the user defined host.
+
+---
+
 ### Custom search
 
 Allows web search using multiple user-defined search engines and other websites.