diff --git a/pdl-live-react/src/pdl_ast.d.ts b/pdl-live-react/src/pdl_ast.d.ts
index 42ba6b15b..4ce93eca4 100644
--- a/pdl-live-react/src/pdl_ast.d.ts
+++ b/pdl-live-react/src/pdl_ast.d.ts
@@ -2917,9 +2917,8 @@ export interface Defs3 {
  *
  * Example:
  * ```PDL
- * - def: N
- *   lang: python
- *   code: |
+ * lang: python
+ * code: |
  *     import random
  *     # (In PDL, set `result` to the output you wish for your code block.)
  *     result = random.randint(1, 20)
@@ -3201,11 +3200,12 @@ export interface Defs7 {
  *
  * Example:
  * ```PDL
- * - if: ${ eval == 'no' }
- *   then:
- *     text:
- *     - read:
- *       message: "Why not?\n"
+ * defs:
+ *   answer:
+ *     read:
+ *     message: "Enter a number? "
+ * if: ${ (answer | int) == 42 }
+ * then: You won!
  * ```
  */
 export interface IfBlock {
@@ -3270,6 +3270,23 @@ export interface Defs8 {
 }
 /**
  * Match control structure.
+ *
+ * Example:
+ * ```PDL
+ * defs:
+ *   answer:
+ *     read:
+ *     message: "Enter a number? "
+ * match: ${ (answer | int) }
+ * with:
+ * - case: 42
+ *   then: You won!
+ * - case:
+ *     any:
+ *     def: x
+ *   if: ${ x > 42 }
+ *   then: Too high
+ * - then: Too low
  */
 export interface MatchBlock {
   description?: Description9
@@ -3706,6 +3723,18 @@ export interface Defs15 {
 }
 /**
  * Read from a file or standard input.
+ *
+ * Example. Read from the standard input with a prompt starting with `> `.
+ * ```PDL
+ * read:
+ * message: "> "
+ * ```
+ *
+ * Example. Read the file `./data.yaml` in the same directory of the PDL file containing the block and parse it into YAML.
+ * ```PDL
+ * read: ./data.yaml
+ * parser: yaml
+ * ```
  */
 export interface ReadBlock {
   description?: Description16
diff --git a/src/pdl/pdl-schema.json b/src/pdl/pdl-schema.json
index 924dc216a..4ff1f4346 100644
--- a/src/pdl/pdl-schema.json
+++ b/src/pdl/pdl-schema.json
@@ -1349,7 +1349,7 @@
     },
     "CodeBlock": {
       "additionalProperties": false,
-      "description": "Execute a piece of code.\n\nExample:\n```PDL\n- def: N\n  lang: python\n  code: |\n    import random\n    # (In PDL, set `result` to the output you wish for your code block.)\n    result = random.randint(1, 20)\n```",
+      "description": "Execute a piece of code.\n\nExample:\n```PDL\nlang: python\ncode: |\n    import random\n    # (In PDL, set `result` to the output you wish for your code block.)\n    result = random.randint(1, 20)\n```",
       "properties": {
         "description": {
           "anyOf": [
@@ -4318,7 +4318,7 @@
     },
     "IfBlock": {
       "additionalProperties": false,
-      "description": "Conditional control structure.\n\nExample:\n```PDL\n- if: ${ eval == 'no' }\n  then:\n    text:\n    - read:\n      message: \"Why not?\\n\"\n```",
+      "description": "Conditional control structure.\n\nExample:\n```PDL\ndefs:\n  answer:\n    read:\n    message: \"Enter a number? \"\nif: ${ (answer | int) == 42 }\nthen: You won!\n```",
       "properties": {
         "description": {
           "anyOf": [
@@ -7186,7 +7186,7 @@
     },
     "MatchBlock": {
       "additionalProperties": false,
-      "description": "Match control structure.",
+      "description": "Match control structure.\n\nExample:\n```PDL\ndefs:\n  answer:\n    read:\n    message: \"Enter a number? \"\nmatch: ${ (answer | int) }\nwith:\n- case: 42\n  then: You won!\n- case:\n    any:\n    def: x\n  if: ${ x > 42 }\n  then: Too high\n- then: Too low",
       "properties": {
         "description": {
           "anyOf": [
@@ -9208,7 +9208,7 @@
     },
     "ReadBlock": {
       "additionalProperties": false,
-      "description": "Read from a file or standard input.",
+      "description": "Read from a file or standard input.\n\nExample. Read from the standard input with a prompt starting with `> `.\n```PDL\nread:\nmessage: \"> \"\n```\n\nExample. Read the file `./data.yaml` in the same directory of the PDL file containing the block and parse it into YAML.\n```PDL\nread: ./data.yaml\nparser: yaml\n```",
       "properties": {
         "description": {
           "anyOf": [
diff --git a/src/pdl/pdl_ast.py b/src/pdl/pdl_ast.py
index 7bf44fcb7..6ca6fc68c 100644
--- a/src/pdl/pdl_ast.py
+++ b/src/pdl/pdl_ast.py
@@ -466,9 +466,8 @@ class CodeBlock(BaseCodeBlock):
 
     Example:
     ```PDL
-    - def: N
-      lang: python
-      code: |
+    lang: python
+    code: |
         import random
         # (In PDL, set `result` to the output you wish for your code block.)
         result = random.randint(1, 20)
@@ -600,11 +599,12 @@ class IfBlock(StructuredBlock):
 
     Example:
     ```PDL
-    - if: ${ eval == 'no' }
-      then:
-        text:
-        - read:
-          message: "Why not?\\n"
+    defs:
+      answer:
+        read:
+        message: "Enter a number? "
+    if: ${ (answer | int) == 42 }
+    then: You won!
     ```
     """
 
@@ -642,7 +642,25 @@ class MatchCase(BaseModel):
 
 
 class MatchBlock(StructuredBlock):
-    """Match control structure."""
+    """Match control structure.
+
+    Example:
+    ```PDL
+    defs:
+      answer:
+        read:
+        message: "Enter a number? "
+    match: ${ (answer | int) }
+    with:
+    - case: 42
+      then: You won!
+    - case:
+        any:
+        def: x
+      if: ${ x > 42 }
+      then: Too high
+    - then: Too low
+    """
 
     kind: Literal[BlockKind.MATCH] = BlockKind.MATCH
     match_: ExpressionType[Any] = Field(alias="match")
@@ -735,7 +753,20 @@ class RepeatBlock(StructuredBlock):
 
 
 class ReadBlock(LeafBlock):
-    """Read from a file or standard input."""
+    """Read from a file or standard input.
+
+    Example. Read from the standard input with a prompt starting with `> `.
+    ```PDL
+    read:
+    message: "> "
+    ```
+
+    Example. Read the file `./data.yaml` in the same directory of the PDL file containing the block and parse it into YAML.
+    ```PDL
+    read: ./data.yaml
+    parser: yaml
+    ```
+    """
 
     kind: Literal[BlockKind.READ] = BlockKind.READ
     read: ExpressionType[str] | None