docs: Clarify Siblings block as Previous/Next navigation

- Update description: Siblings is for Previous/Next navigation, not same-level docs
- Typically placed at bottom of page for sequential navigation
- Perfect for tutorial series (Part 1 → Part 2 → Part 3)
- Update examples to show bottom placement
- Add visual layout diagram to example output

Author: m-brtn

CHANGELOG.md

@@ -16,11 +16,12 @@
   - Shows backlinks (documents linking to this one)
   - Visualizes knowledge graph connections
 
-- **📄 Siblings Block**: Same-level document navigation
-  - `siblings_block()` - Shows sibling documents
-  - Displays documents in same folder/collection
-  - Helps navigate series of related pages
-  - Useful for guides and tutorials
+- **📄 Siblings Block**: Previous/Next document navigation
+  - `siblings_block()` - Creates Previous/Next navigation buttons
+  - Shows Previous and Next documents in sequence
+  - Typically placed at the bottom of the page
+  - Perfect for tutorial series and sequential guides
+  - Maintains document order in branch
 
 - **💻 Code Block**: Syntax-highlighted code snippets
   - `code_block(code, language)` - Display code with highlighting

docs-site/docs/api-reference/document-structure.md

@@ -970,7 +970,7 @@ client.replace_json_document(document_id, content)
 
 ### Siblings Block
 
-Displays documents at the same hierarchical level.
+Previous/Next navigation between documents in a sequence.
 
 **Structure:**
 ```json
@@ -992,23 +992,32 @@ Displays documents at the same hierarchical level.
 
 **Using Helper:**
 ```python
-from vaiz import siblings_block, heading, paragraph
+from vaiz import siblings_block, heading, paragraph, horizontal_rule
 
 content = [
-    siblings_block(),
+    heading(1, "Tutorial Part 2: Advanced Features"),
+    paragraph("Main content here..."),
 
-    heading(1, "Tutorial Part 2"),
-    paragraph("See related parts above...")
+    horizontal_rule(),
+    
+    # Navigation at the bottom
+    siblings_block()  # Shows "← Part 1" and "Part 3 →"
 ]
 
 client.replace_json_document(document_id, content)
 ```
 
-**Useful for:**
-- Tutorial series navigation
-- Multi-part guides
-- Documentation pages at same level
-- Folder/collection browsing
+**Features:**
+- Shows Previous and Next documents in sequence
+- Creates navigation buttons (Back/Forward)
+- Typically placed at page bottom
+- Maintains document order in branch
+
+**Best for:**
+- Tutorial series (Part 1 → Part 2 → Part 3)
+- Multi-chapter guides  
+- Sequential documentation
+- Step-by-step workflows
 
 ---
 

docs-site/docs/guides/document-structure-helpers.md

@@ -712,28 +712,37 @@ client.replace_json_document(document_id, content)
 - Related documents from the space
 - Knowledge graph connections
 
-### Siblings Block - Same-Level Documents
+### Siblings Block - Previous/Next Navigation
 
-Display documents at the same hierarchical level:
+Display Previous/Next navigation between documents in a sequence:
 
 ```python
-from vaiz import siblings_block, heading, paragraph
+from vaiz import siblings_block, heading, paragraph, horizontal_rule
 
 content = [
-    siblings_block(),  # Shows sibling documents
+    heading(1, "Tutorial Part 2: Advanced Features"),
+    paragraph("Main tutorial content here..."),
 
-    heading(1, "Current Page"),
-    paragraph("Sibling pages shown above...")
+    horizontal_rule(),
+    
+    # Navigation at the bottom
+    siblings_block()  # Shows "← Previous" and "Next →" buttons
 ]
 
 client.replace_json_document(document_id, content)
 ```
 
+**Features:**
+- Shows Previous and Next documents in sequence
+- Creates navigation buttons (Back/Forward)
+- Typically placed at page bottom
+- Perfect for linear document flows
+
 **Useful for:**
-- Series of tutorial pages
-- Multi-part guides
-- Related documentation pages
-- Folder/collection navigation
+- Tutorial series (Part 1 → Part 2 → Part 3)
+- Multi-chapter guides
+- Documentation sequences
+- Step-by-step workflows
 
 ### Code Block - Syntax Highlighting
 
@@ -775,22 +784,23 @@ client.replace_json_document(document_id, content)
 
 ### Complete Navigation Example
 
-Combine all navigation blocks:
+Combine all navigation blocks for optimal user experience:
 
 ```python
 from vaiz import (
     toc_block, anchors_block, siblings_block,
-    heading, paragraph, code_block, bullet_list
+    heading, paragraph, code_block, bullet_list, horizontal_rule
 )
 
 content = [
-    # All navigation blocks at the top
+    # Top navigation: TOC and related documents
     toc_block(),
     anchors_block(),
-    siblings_block(),
+    
+    horizontal_rule(),
 
     # Main content
-    heading(1, "API Documentation"),
+    heading(1, "API Documentation - Part 2"),
 
     paragraph("This guide explains how to use our API."),
 
@@ -805,12 +815,22 @@ content = [
     code_block(
         code='client = VaizClient(api_key="...")',
         language="python"
-    )
+    ),
+    
+    horizontal_rule(),
+    
+    # Bottom navigation: Previous/Next pages
+    siblings_block()  # Shows "← Part 1" and "Part 3 →"
 ]
 
 client.replace_json_document(document_id, content)
 ```
 
+**Navigation Layout:**
+- **Top**: TOC (internal navigation) + Anchors (related docs)
+- **Content**: Your document content
+- **Bottom**: Siblings (Previous/Next in sequence)
+
 ## Supported Elements
 
 All helper functions create nodes compatible with the document editor:

examples/document_navigation_blocks.py

@@ -2,9 +2,9 @@
 Example demonstrating all document navigation blocks: TOC, Anchors, and Siblings.
 
 This example shows how to create a document with automatic navigation features:
-- Table of Contents (TOC) for internal document navigation
-- Anchors for displaying related documents and backlinks
-- Siblings for showing documents at the same hierarchical level
+- Table of Contents (TOC) for internal document navigation (top)
+- Anchors for displaying related documents and backlinks (top)
+- Siblings for Previous/Next navigation between documents (bottom)
 """
 
 from config import get_client
@@ -31,15 +31,10 @@
 
 # Create document content with all navigation blocks
 content = [
-    # Automatic table of contents
+    # Top navigation: TOC and related documents
     toc_block(),
-    
-    # Related documents and backlinks
     anchors_block(),
 
-    # Sibling documents navigation
-    siblings_block(),
-    
     horizontal_rule(),
 
     # Main content
@@ -81,18 +76,19 @@
         "Related documents from the same space"
     ),
 
-    heading(2, "Siblings Block - Same Level Documents"),
+    heading(2, "Siblings Block - Previous/Next Navigation"),
 
     paragraph(
         "The ",
         text("siblings_block()", code=True),
-        " shows documents at the same hierarchical level:"
+        " provides Previous/Next navigation between documents in a sequence:"
     ),
 
     bullet_list(
-        "Documents in the same folder/collection",
-        "Documents at the same level in structure",
-        "Useful for series of related pages (guides, tutorials)"
+        "Shows Previous and Next documents in the sequence",
+        "Creates navigation buttons (Back/Forward)",
+        "Typically placed at the bottom of the page",
+        "Perfect for tutorial series and sequential guides"
     ),
 
     horizontal_rule(),
@@ -119,15 +115,23 @@
     heading(2, "All Navigation Blocks Together"),
 
     paragraph(text(
-        '''from vaiz import toc_block, anchors_block, siblings_block
+        '''from vaiz import toc_block, anchors_block, siblings_block, horizontal_rule
 
 content = [
+    # Top navigation
     toc_block(),        # Table of contents
     anchors_block(),    # Related documents
-    siblings_block(),   # Sibling documents
     
-    heading(1, "Main Content"),
-    paragraph("Your content here...")
+    horizontal_rule(),
+    
+    # Your content
+    heading(1, "Tutorial Part 2"),
+    paragraph("Main content here..."),
+    
+    horizontal_rule(),
+    
+    # Bottom navigation
+    siblings_block()    # Previous/Next buttons
 ]
 
 client.replace_json_document(document_id, content)''',
@@ -139,9 +143,10 @@
     heading(1, "Best Practices"),
 
     bullet_list(
-        "Place TOC block at the document start for better accessibility",
+        "Place TOC and Anchors blocks at the document start for better accessibility",
+        "Place Siblings block at the document end for Previous/Next navigation",
         "Use Anchors block for documentation with cross-references",
-        "Use Siblings block for series of related pages",
+        "Use Siblings block for tutorial series and sequential guides",
         "For short documents (< 3 sections), TOC may be redundant"
     ),
 
@@ -151,17 +156,32 @@
         text("mention_document()", code=True),
         " to create links between documents and populate the Anchors block!"
     ),
+    
+    horizontal_rule(),
+    
+    # Bottom navigation - demonstrate siblings placement
+    siblings_block(),
 ]
 
 try:
     response = client.replace_json_document(DOCUMENT_ID, content)
     print("✅ Document created successfully!")
     print()
     print("What was added:")
-    print("  • TOC block - automatic table of contents")
-    print("  • Anchors block - related documents and backlinks")
-    print("  • Siblings block - same-level documents")
-    print("  • Headings with UIDs for navigation")
+    print("  • TOC block (top) - automatic table of contents")
+    print("  • Anchors block (top) - related documents and backlinks")
+    print("  • Siblings block (bottom) - Previous/Next navigation")
+    print("  • Headings with UIDs for TOC navigation")
+    print()
+    print("Navigation layout:")
+    print("  ┌─────────────────────────┐")
+    print("  │ TOC Block               │  ← Internal navigation")
+    print("  │ Anchors Block           │  ← Related docs")
+    print("  ├─────────────────────────┤")
+    print("  │ Content...              │")
+    print("  ├─────────────────────────┤")
+    print("  │ Siblings Block          │  ← Previous/Next")
+    print("  └─────────────────────────┘")
     print()
     print(f"Open document in Vaiz: {DOCUMENT_ID}")
     print()

vaiz/helpers/document_structure.py

@@ -1135,21 +1135,23 @@ def anchors_block() -> DocSiblingsNode:
 
 def siblings_block() -> DocSiblingsNode:
     """
-    Create a Siblings block that displays sibling documents (documents at the same level).
+    Create a Siblings block for Previous/Next document navigation.
     
-    This block automatically shows documents that are siblings in the document hierarchy:
-    - Documents in the same folder/collection
-    - Documents at the same level in the structure
+    This block provides navigation between documents in the same branch/sequence:
+    - Shows Previous and Next documents in the sequence
+    - Typically placed at the bottom of the page
+    - Perfect for tutorial series, guides, and documentation chapters
+    - Creates "Back" and "Forward" navigation buttons
     
     Returns:
         DocSiblingsNode: A valid Siblings block node
         
     Example:
         >>> from vaiz import siblings_block, heading, paragraph
         >>> content = [
-        ...     siblings_block(),
-        ...     heading(1, "Current Document"),
-        ...     paragraph("Sibling documents will be shown above")
+        ...     heading(1, "Tutorial Part 2"),
+        ...     paragraph("Main content here..."),
+        ...     siblings_block()  # Navigation at the bottom
         ... ]
         >>> client.replace_json_document(document_id, content)
     """