haddock2/markup.md

# Haddock Markup Language Examples

## Text Formatting

### Emphasis
```
/emphasized text/
```
Single line only, no newlines allowed.

### Bold
```
__bold text__
```
Single line only, no newlines allowed.

### Monospace/Code
```
@monospace text@
```
Can span multiple lines.

## Links and References

### Module Links
```
"Module.Name"
"Module.Name#anchor"
"Module.Name\#anchor"
```

### Hyperlinks
```
<http://example.com>
<http://example.com label text>
```
Auto-detected URLs:
```
http://example.com
https://example.com
ftp://example.com
```

### Markdown-style Links
```
[link text](http://example.com)
[link text]("Module.Name")
```

### Anchors
```
#anchor-name#
```
No spaces allowed in anchor names.

### Identifiers
```
'identifier'
```
Links to Haskell identifiers.

## Images

### Basic Images
```
<<image.png>>
<<image.png title text>>
```

### Markdown Images
```
![alt text](image.png)
```

## Math

### Inline Math
```
\(mathematical expression\)
```
Single line only.

### Display Math
```
\[mathematical expression\]
```
Can span multiple lines.

## Code and Examples

### Code Blocks
```
@
code block content
with multiple lines
@
```

### Bird Tracks (Code)
```
> code line 1
> code line 2
```
Each line starts with `>` followed by optional space.

### Examples
```
>>> expression
result line 1
result line 2

>>> another expression
result
```

### Properties
```
prop> property description
```

## Lists

### Unordered Lists
```
* item 1
* item 2
  continued content

- item 1
- item 2
```

### Ordered Lists
```
1. item 1
2. item 2

(1) item 1
(2) item 2
```

### Definition Lists
```
[term] definition content
[another term] more definition content
```
Optional colon after closing bracket.

## Tables

### Grid Tables
```
+----------+----------+
| Header 1 | Header 2 |
+==========+==========+
| Cell 1   | Cell 2   |
+----------+----------+
| Cell 3   | Cell 4   |
+----------+----------+
```
- First row determines table width
- Header separator uses `=` characters
- Regular separators use `-`
- Edges can be `+` or `|`

## Headers
```
= Level 1 Header
== Level 2 Header
=== Level 3 Header
==== Level 4 Header
===== Level 5 Header
====== Level 6 Header
```
Up to 6 levels deep.

## Special Elements

### Since Annotations
```
@since package-name-1.2.3
@since 1.2.3
```

### Numeric Character References
```
&#65;     (decimal)
&#x41;    (hexadecimal)
&#X41;    (hexadecimal)
```

## Escaping
Use backslash `\` to escape special characters. Trailing backslash without following character is treated as literal backslash.

## Structure
- Paragraphs separated by blank lines
- 4-space indentation for nested content
- Whitespace handling varies by context