# Void Elements

Void elements are self-closing elements that cannot have any content. They are complete in themselves - no children, no nested blocks, no text content. Think of them as single, standalone markers in your document.

## Inspiration

Void elements in wasot are inspired by [HTML void elements](https://html.spec.whatwg.org/multipage/syntax.html#void-elements). In HTML, elements like `<br>`, `<hr>`, `<img>`, and `<input>` are void - they have only a start tag with no corresponding end tag because they cannot contain content.

Wasot adopts this concept to provide a clean way to express standalone markers without the overhead of opening and closing a block.

## Syntax

A void element is marked with a trailing colon (`:`) after the type name:

```wasot
.hr:                                    # Basic void element
.img: alt text here                     # Void element with inline text
.img: alt text .. src="photo.jpg"       # Void element with arguments
.img: alt text .. src="x.jpg" :img1     # Void element with ID
..nested-void:                          # Nested void element (level 2)
."custom type":                         # Void element with quoted type name
```

Compare this to regular blocks:

```wasot
.paragraph                              # Regular block (needs content or explicit close)
Some content here.
./                                      # Explicit close

.hr:                                    # Void element (self-closing, no content)
```

## When to Use Void Elements

Void elements are ideal for:

- **Separators**: Horizontal rules, page breaks, section dividers
- **Media references**: Images, audio, video embeds (content is external)
- **Self-contained markers**: Anchors, bookmarks, timestamps
- **Metadata points**: Markers that don't wrap content but mark a position

## Syntax Details

The void marker is the colon (`:`) immediately after the type name:

| Component | Regular Block | Void Element |
|-----------|--------------|--------------|
| Type | `.paragraph` | `.paragraph:` |
| With inline text | `.note A note` | `.note: A note` |
| With arguments | `.img .. src="x.jpg"` | `.img: .. src="x.jpg"` |
| With ID | `.section :sec1` | `.section: :sec1` |
| Nested (level 2) | `..quote` | `..quote:` |
| Quoted type | `."my type"` | `."my type":` |

## Behavior

Void elements differ from regular blocks in important ways:

1. **No content**: Void elements cannot contain text or nested blocks
2. **No closing**: They don't need (or accept) a `./` close marker
3. **No stack impact**: They don't affect block nesting - subsequent blocks nest as if the void element wasn't there
4. **Self-contained**: All information is on the single line

```wasot
.document
This is inside the document.

.hr:                      # This void element doesn't affect nesting

Still inside the document, not affected by the hr.
./
```

## XML Representation

When converted to XML, void elements are represented as self-closing tags with a `void="true"` attribute:

```xml
<block type="hr" level="1" void="true" />
```

This distinguishes them from empty blocks (which might later receive content):

```xml
<!-- Empty block (could have content) -->
<block type="placeholder" level="1"></block>

<!-- Void element (semantically cannot have content) -->
<block type="hr" level="1" void="true" />
```

## Complete Example

```wasot
.article
.# Introduction:                        # Void heading

This article explores wasot void elements.

.img: A beautiful sunset .. src="sunset.jpg" alt="Sunset over mountains" :fig1

The image above shows the sunset.

.hr:                                    # Section divider

.# Methods:

We used the following approach...

.br:                                    # Line break

.timestamp: 2024-01-15 :ts1             # Metadata marker
./
```

## Related Documentation

- [Wasot and XML](./wasot_and_xml.md) - Data model and XML mapping
- [AST](./ast.md) - Abstract syntax tree structure
- [Architecture](./architecture.md) - Event-driven processing model
