updated docs

README.adoc

@@ -38,11 +38,18 @@ This project was developed with the assistance of an AI language model (GPT-4) a
 |HEAD003
 |Detect multiple top-level headers
 |ERROR
+
+|BLOCK001
+|Check for unterminated blocks (listing, example, sidebar, etc.)
+|ERROR
+
+|BLOCK002
+|Verify proper spacing around blocks
+|WARNING
 |===
 
 === Planned Rules
 
-* BLOCK001: Unterminated block warnings
 * WS001: Blank lines around headers and blocks
 * TABLE001: Table formatting consistency
 * IMG001: Image alt text presence
@@ -99,6 +106,12 @@ ERROR: Heading level skipped: found h3 after h1 (line 15)
 WARNING: Heading should start with uppercase letter (line 23)
   == introduction to concepts
 
+ERROR: Unterminated listing block starting (line 45)
+  ----
+
+WARNING: Block should be preceded by a blank line (line 67)
+  ----
+
 ERROR: Multiple top-level headings found (line 30)
   First heading at line 1: 'Document Title'
 ----
@@ -126,13 +139,16 @@ asciidoc-linter/
 │   ├── cli.py
 │   ├── rules.py
 │   ├── heading_rules.py
+│   ├── block_rules.py
 │   ├── parser.py
 │   └── reporter.py
 ├── tests/
 │   └── rules/
-│       └── test_heading_rules.py
+│       ├── test_heading_rules.py
+│       └── test_block_rules.py
 ├── docs/
-│   └── requirements.adoc
+│   ├── requirements.adoc
+│   └── block_rules.adoc
 ├── README.adoc
 └── run_tests.py
 ----
@@ -162,7 +178,7 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 1. Phase 1 (Current)
 * ✅ Basic heading rules
-* ⏳ Block structure rules
+* ✅ Block structure rules
 * ⏳ Configuration system
 
 2. Phase 2

README.adoc.meta

@@ -1 +1 @@
-Project README file
+Main documentation file for the AsciiDoc Linter project

docs/block_rules.adoc

@@ -0,0 +1,113 @@
+// block_rules.adoc - Documentation for block-related rules
+= Block Rules Documentation
+:toc: left
+:icons: font
+:source-highlighter: rouge
+
+== BLOCK001: Unterminated Block Check
+
+=== Purpose
+This rule checks for blocks in AsciiDoc files that are not properly terminated. It helps prevent incomplete or malformed block structures that could lead to incorrect rendering.
+
+=== Severity
+ERROR
+
+=== Supported Block Types
+* Listing blocks (`----`)
+* Example blocks (`====`)
+* Sidebar blocks (`****`)
+* Literal blocks (`....`)
+* Quote blocks (`____`)
+* Table blocks (`|===`)
+* Comment blocks (`////`)
+* Passthrough blocks (`++++`)
+
+=== Examples
+
+==== Valid Block Structure
+[source,asciidoc]
+----
+.Example Title
+====
+This is an example block.
+It has proper opening and closing delimiters.
+====
+----
+
+==== Invalid Block Structure
+[source,asciidoc]
+----
+.Example Title
+====
+This block is not properly terminated.
+More content...
+----
+
+=== Error Messages
+* "Unterminated listing block starting"
+* "Unterminated example block starting"
+* "Unterminated sidebar block starting"
+* (similar messages for other block types)
+
+== BLOCK002: Block Spacing Check
+
+=== Purpose
+This rule ensures proper spacing around blocks by checking for blank lines before and after block structures. Proper spacing improves readability and follows AsciiDoc best practices.
+
+=== Severity
+WARNING
+
+=== Rules
+1. A blank line should precede a block (except when it follows a heading)
+2. A blank line should follow a block (except when it's followed by a heading)
+
+=== Examples
+
+==== Valid Block Spacing
+[source,asciidoc]
+----
+Some text before the block.
+
+----
+Block content
+----
+
+More text after the block.
+----
+
+==== Invalid Block Spacing
+[source,asciidoc]
+----
+Some text before the block.
+----
+Block content
+----
+More text after the block.
+----
+
+=== Error Messages
+* "Block should be preceded by a blank line"
+* "Block should be followed by a blank line"
+
+=== Special Cases
+* Blocks immediately following headings don't require a preceding blank line
+* Blocks immediately followed by headings don't require a following blank line
+
+== Implementation Details
+
+=== Rule Classes
+* `UnterminatedBlockRule`: Implements BLOCK001
+* `BlockSpacingRule`: Implements BLOCK002
+
+=== Configuration
+Currently, these rules are not configurable. Future versions may allow:
+
+* Custom block types
+* Adjustable severity levels
+* Exceptions for specific block types
+* Custom spacing requirements
+
+=== Performance Considerations
+* Both rules process files line by line
+* Block tracking uses minimal memory
+* Processing time is O(n) where n is the number of lines

docs/block_rules.adoc.meta

@@ -0,0 +1 @@
+Documentation for block-related rules