From 2ca09bdc3798abb31960c433d8cb020a2eea6554 Mon Sep 17 00:00:00 2001
From: Ramon Wenger <ramon.wenger@iterativ.ch>
Date: Mon, 13 Mar 2023 15:43:01 +0100
Subject: [PATCH] Add documentation for using a StructBlock inside of a
 StreamField

Fixes #10231
---
 CHANGELOG.txt              |  1 +
 CONTRIBUTORS.rst           |  1 +
 docs/releases/5.1.md       |  1 +
 docs/topics/streamfield.md | 23 +++++++++++++++++++++++
 4 files changed, 26 insertions(+)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index 73be3ce14c..ad91320fb0 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -6,6 +6,7 @@ Changelog
 
  * Fix: Prevent choosers from failing when initial value is an unrecognised ID, e.g. when moving a page from a location where `parent_page_types` would disallow it (Dan Braghis)
  * Docs: Document how to add non-ModelAdmin views to a `ModelAdminGroup` (Onno Timmerman)
+ * Docs: Document how to add StructBlock data to a StreamField (Ramon Wenger)
  * Maintenance: Switch to ruff for flake8 / isort code checking (Oliver Parker)
 
 
diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst
index 7e346502a3..d23a8d0576 100644
--- a/CONTRIBUTORS.rst
+++ b/CONTRIBUTORS.rst
@@ -708,6 +708,7 @@ Contributors
 * Steve Steinwand
 * Swojak-A
 * fidoriel
+* Ramon Wenger
 
 Translators
 ===========
diff --git a/docs/releases/5.1.md b/docs/releases/5.1.md
index c5be263b68..50a0a069a9 100644
--- a/docs/releases/5.1.md
+++ b/docs/releases/5.1.md
@@ -24,6 +24,7 @@ depth: 1
 ### Documentation
 
  * Document how to add non-ModelAdmin views to a `ModelAdminGroup` (Onno Timmerman)
+ * Document how to add StructBlock data to a StreamField (Ramon Wenger)
 
 ### Maintenance
 
diff --git a/docs/topics/streamfield.md b/docs/topics/streamfield.md
index b7064c1a52..b2ae641ada 100644
--- a/docs/topics/streamfield.md
+++ b/docs/topics/streamfield.md
@@ -519,6 +519,29 @@ my_page.body.append(('paragraph', RichText("<p>And they all lived happily ever a
 my_page.save()
 ```
 
+If a block extending a StructBlock is to be used inside of the StreamField's value, the value of this block can be provided as a python dict (similar in what is accepted by the block's `.to_python` method).
+
+```python
+
+from wagtail import blocks
+
+class UrlWithTextBlock(blocks.StructBlock):
+   url = blocks.URLBlock()
+   text = blocks.TextBlock()
+
+# using this block inside the content
+
+data = {
+    'url': 'https://github.com/wagtail/',
+    'text': 'A very interesting and useful repo'
+}
+
+# append the new block to the stream as a tuple with the defined index for this block type
+my_page.body.append(('url', data))
+my_page.save()
+
+```
+
 (streamfield_retrieving_blocks_by_name)=
 
 ## Retrieving blocks by name