From c776cf64185b2d4881a79eba6d9b8bd60c7154ca Mon Sep 17 00:00:00 2001
From: Leena Gupte <leena.gupte@digital.cabinet-office.gov.uk>
Date: Thu, 24 Oct 2024 14:51:36 +0100
Subject: [PATCH] Create guidance for building flexible blocks

Documents what each of the blocks is, when they should be used and how
they are configured.
---
 docs/building_blocks_for_flexible_content.md | 67 ++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/building_blocks_for_flexible_content.md

diff --git a/docs/building_blocks_for_flexible_content.md b/docs/building_blocks_for_flexible_content.md
new file mode 100644
index 0000000000..30f55b9045
--- /dev/null
+++ b/docs/building_blocks_for_flexible_content.md
@@ -0,0 +1,67 @@
+# Building blocks for flexible content
+
+The "landing-page" document type will allow content designers to build pages with a flexible design by creating a "block" that renders certain parts of the page.
+
+Blocks can be nested within each other. A top-level block is a horizontal chunk of the page.
+
+Blocks are rendered in the order that they appear in the content item.
+
+## Types of Block
+
+Each block has its own partial template. The full list of available types of block available can be found by looking at the contents of: `app/views/landing_page/blocks`
+
+### Simple blocks
+
+Simple blocks general render one component or "thing". They can either be rendered directly or as the children of compound blocks.
+
+- Action link
+- Big number
+- Document list
+- Govspeak
+- Heading
+- Image
+- Main Navigation
+- Quote
+- Share links
+- Side Navigation
+- Statistics
+- Tabs
+
+### Compound blocks
+
+Compound blocks generally render more than one component and can contain nested blocks. The nested blocks can be simple blocks or themselves compound blocks
+
+- Card
+- Featured
+- Hero
+
+#### Layout blocks
+
+- Blocks container
+- Columns layout
+- Grid Container
+- Two column layout
+
+
+## Indexing block content in search
+
+Only content in blocks that has a label of `content` will be indexed in site search.
+
+```json
+{"blocks":
+    [
+        { 
+            "type": "govspeak", 
+            "content": "## This will be a searchable header\nhere's some content that's searchable\n"}
+        {   
+            "type": "button", 
+            "text": "Press me (not searchable)"}
+        {
+            "type": "header", 
+            "content": "searchable header"
+        }
+    ]
+}
+```
+
+In the example above only the text in the govspeak and header blocks will be searchable.
\ No newline at end of file