# BlockMD Specification
`version`: 1.0.0
`status`: draft
`author`: GitHub Copilot

BlockMD is a block-based markup language that is fully compatible with Markdown. It adds structure and metadata capabilities to standard Markdown files.

## Syntax Overview
`section`: syntax
`importance`: high

A BlockMD file consists of a hierarchy of blocks. Each block is defined by a Markdown header.

### Block Definition
`type`: definition

A block starts with a Markdown header line (e.g., `#`, `##`, `###`).
The number of hash signs determines the nesting level of the block.

### Block Properties
`type`: definition

Properties are key-value pairs that provide metadata for the block.
- They must appear immediately after the header line.
- Syntax: `` `key`: value `` or `` `key*`: value `` (for inheritance)
- Keys should be alphanumeric (can include hyphens/underscores).
- Values are strings.

#### Property Inheritance
`type`: feature

If a property key ends with `*` (e.g., `` `status*`: doing ``), it inherits the value from the parent block's property of the same name (without the `*`).
- The inherited value is appended with a slash `/`.
- Example: Parent `` `status`: TODO `` + Child `` `status*`: doing `` = Child `` `status`: TODO/doing ``.
- If the parent does not have the property, the value is used as is.

### Block Content
`type`: definition

The content of a block is standard Markdown text.
It starts after the properties (if any) and continues until the next header of the same or higher level (lower number of hashes).

## Example
`section`: example

```markdown
# Root Block
`id`: root
`type`: container

This is the content of the root block.

## Child Block
`id`: child1
`parent`: root

This is a child block.
```

## Parser Implementation
`section`: implementation
`language`: python

A reference implementation is provided in `src/blockmd.py`.
It uses AST-based parsing to build a tree of Block objects, each containing:
- title: str - The header text
- level: int - Header nesting level (1-6)
- properties: dict - Key-value metadata pairs
- content: str - Markdown content body
- children: list[Block] - Nested child blocks

### Parser Design
`type`: technical

The parser uses Abstract Syntax Tree (AST) approach:
1. Line-by-line scanning for structure detection
2. Stack-based hierarchy management for parent-child relationships
3. State machine for property vs content parsing
4. Property inheritance resolved during parsing phase
