@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/docs.md

@@ -1,524 +1,1640 @@
 ---
 id: docs
-title: "Docs Reference"
+title: "ZIO Blocks Docs (Markdown)"
+sidebar_label: "Docs"
 ---
 
-# Docs Module Reference
+ZIO Blocks Markdown is a **pure, zero-dependency GitHub Flavored Markdown library** providing an immutable ADT for markdown documents, a strict parser with error handling, multiple renderers (GFM markdown, HTML, terminal), and a compile-time validated string interpolator. Core types: `Doc`, `Block`, `Inline`, `Parser`, `Renderer`, `ToMarkdown`.
 
-Complete API reference for the zio-blocks-docs module - a zero-dependency GitHub Flavored Markdown library.
+Here are the core type definitions:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+final case class Doc(blocks: Chunk[Block], metadata: Map[String, String] = Map.empty)
+
+sealed trait Block extends Product with Serializable
+final case class Paragraph(content: Chunk[Inline]) extends Block
+final case class Heading(level: HeadingLevel, content: Chunk[Inline]) extends Block
+final case class CodeBlock(info: Option[String], code: String) extends Block
+
+sealed trait Inline extends Product with Serializable
+final case class Text(value: String) extends Inline
+final case class Code(value: String) extends Inline
+final case class Link(text: Chunk[Inline], url: String, title: Option[String]) extends Inline
+```
+
+## Motivation
+
+Markdown is the de facto standard for documentation, READMEs, and formatted text in software development. However, parsing and generating markdown at runtime often requires hand-crafted parsers or fragile string concatenation. ZIO Blocks Markdown provides:
+
+- **Type-safe ADT**: Every markdown element is a Scala case class—no stringly-typed HTML generation
+- **Strict parsing**: Rejects invalid markdown with precise error locations (line, column)
+- **Round-trip semantics**: Parse-render-parse cycles preserve document structure
+- **Normalized equality**: Two documents are equal if their normalized forms are equal (adjacent text nodes merged, empty blocks removed)
+- **Multiple output formats**: Render to GFM markdown, HTML (full document or fragment), or colorized terminal
+- **Compile-time validation**: The `md"..."` string interpolator validates markdown syntax at compile time, catching errors before runtime
+- **Type class system**: `ToMarkdown` lets you interpolate custom types into markdown documents
 
 ## Installation
 
-```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-docs" % "0.0.33"
+Add the dependency to your `build.sbt`:
+
+```sbt
+libraryDependencies += "dev.zio" %% "zio-blocks-markdown" % "0.0.51"
 ```
 
-## Core Types
+For Scala.js, use the cross-build syntax:
 
-### Doc
+```sbt
+libraryDependencies += "dev.zio" %%% "zio-blocks-markdown" % "0.0.51"
+```
 
-The top-level document container. A `Doc` wraps a `Chunk[Block]` representing the document's block-level elements, plus optional metadata.
+Supported Scala versions: 2.13.x and 3.x
+
+## How They Work Together
+
+Markdown documents flow through a **parsing → normalization → rendering pipeline**:
 
-```scala
-final case class Doc(blocks: Chunk[Block], metadata: Map[String, String] = Map.empty)
 ```
+Markdown String ──> Parser ──> Doc (blocks) ──> Renderer ──> Markdown/HTML/Terminal
+                        │           │
+                    ParseError   ToMarkdown
+                                (type class)
+
+Doc = Chunk[Block]
+Block = Paragraph | Heading | CodeBlock | List | Table | ... (contains Inlines)
+Inline = Text | Code | Emphasis | Strong | Link | Image | ... (leaf nodes)
+```
+
+**Typical workflow:**
 
-**Key methods:**
-- `++`: Concatenate two documents (merges blocks and metadata, right wins on conflicts)
-- `normalize`: Merge adjacent Text nodes and remove empty blocks
-- `toHtml`: Render to full HTML5 document (with DOCTYPE, html, head, body tags)
-- `toHtmlFragment`: Render to HTML content only (no html/head/body wrapper)
-- `toTerminal`: Render with ANSI escape codes for terminal display
-- `toString`: Render back to GFM Markdown
+1. **Parse markdown** — `Parser.parse("# Hello")` returns `Either[ParseError, Doc]`
+2. **Build programmatically** — construct `Doc` with `Heading`, `Paragraph`, `BulletList`, etc.
+3. **Normalize** — `doc.normalize` merges adjacent text, removes empty blocks
+4. **Render to desired format** — GFM (`Renderer.render`), HTML (`HtmlRenderer.render`), terminal (`TerminalRenderer.render`)
+5. **Use interpolator** — `md"# Title with $interpolation"` validates markdown at compile time
 
-**Equality:** Two documents are equal if their normalized forms are equal.
+Here's a complete example of composing a document:
 
-**Example:**
 ```scala
+import zio.blocks.chunk.Chunk
 import zio.blocks.docs._
 
-val doc = Parser.parse("# Hello World").toOption.get
-val markdown = doc.toString           // "# Hello World\n"
-val html = doc.toHtml                 // Full HTML5 document
-val fragment = doc.toHtmlFragment     // Just the content
-val terminal = doc.toTerminal         // ANSI colored output
+val doc = Doc(Chunk(
+  Heading(HeadingLevel.H1, Chunk(Text("My Document"))),
+  Paragraph(Chunk(Text("This is a paragraph with "), Strong(Chunk(Text("bold"))), Text(" text."))),
+  CodeBlock(Some("scala"), "val x = 42"),
+  BulletList(Chunk(
+    ListItem(Chunk(Paragraph(Chunk(Text("Item 1")))), None),
+    ListItem(Chunk(Paragraph(Chunk(Text("Item 2")))), None)
+  ), tight = true)
+))
 ```
 
-### Block
+Rendering to GFM markdown:
 
-Block-level elements that make up a document:
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-| Variant | Description |
-|---------|-------------|
-| `Paragraph(content: Chunk[Inline])` | A paragraph of inline content |
-| `Heading(level: HeadingLevel, content: Chunk[Inline])` | ATX heading (H1-H6) |
-| `CodeBlock(info: Option[String], code: String)` | Fenced code block with optional language |
-| `ThematicBreak` | Horizontal rule (`---`, `***`, `___`) |
-| `BlockQuote(content: Chunk[Block])` | Quoted block content |
-| `BulletList(items: Chunk[ListItem], tight: Boolean)` | Unordered list |
-| `OrderedList(start: Int, items: Chunk[ListItem], tight: Boolean)` | Ordered list with start number |
-| `ListItem(content: Chunk[Block], checked: Option[Boolean])` | List item, optionally a task item |
-| `HtmlBlock(content: String)` | Raw HTML block |
-| `Table(header: TableRow, alignments: Chunk[Alignment], rows: Chunk[TableRow])` | GFM table |
+Renderer.render(doc)
+// res0: String = """# My Document
+// This is a paragraph with **bold** text.
+// 
+// ```scala
+// val x = 42
+// ```
+// - Item 1
+// - Item 2
+// """
+```
 
-**Note on Lists:** The `tight` parameter indicates whether the list should be rendered without blank lines between items (tight) or with blank lines (loose).
+Rendering to HTML:
 
-### Inline
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-Inline elements within blocks:
+HtmlRenderer.render(doc)
+// res1: String = "<!DOCTYPE html><html><head></head><body><h1>My Document</h1><p>This is a paragraph with <strong>bold</strong> text.</p><pre><code class=\"language-scala\">val x = 42</code></pre><ul><li><p>Item 1</p></li><li><p>Item 2</p></li></ul></body></html>"
+```
 
-| Variant | Description |
-|---------|-------------|
-| `Text(value: String)` | Plain text |
-| `Code(value: String)` | Inline code (backticks) |
-| `Emphasis(content: Chunk[Inline])` | Italic text (`*text*` or `_text_`) |
-| `Strong(content: Chunk[Inline])` | Bold text (`**text**` or `__text__`) |
-| `Strikethrough(content: Chunk[Inline])` | Strikethrough (`~~text~~`) |
-| `Link(text: Chunk[Inline], url: String, title: Option[String])` | Hyperlink |
-| `Image(alt: String, url: String, title: Option[String])` | Image |
-| `HtmlInline(content: String)` | Raw inline HTML |
-| `SoftBreak` | Soft line break (rendered as space in HTML) |
-| `HardBreak` | Hard line break (two spaces or backslash before newline) |
-| `Autolink(url: String, isEmail: Boolean)` | Auto-detected URL or email |
+Rendering to terminal:
 
-**Note:** Both top-level case classes and `Inline.X` nested variants exist for compatibility. They are treated identically.
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### HeadingLevel
+TerminalRenderer.render(doc)
+// res2: String = """My Document
+// 
+// This is a paragraph with bold text.
+// 
+// val x = 42
+// 
+// • Item 1
+// • Item 2
+// """
+```
 
-Heading levels H1 through H6:
+Parsing markdown strings to create documents:
 
 ```scala
-sealed abstract class HeadingLevel(val value: Int)
-object HeadingLevel {
-  case object H1 extends HeadingLevel(1)
-  case object H2 extends HeadingLevel(2)
-  case object H3 extends HeadingLevel(3)
-  case object H4 extends HeadingLevel(4)
-  case object H5 extends HeadingLevel(5)
-  case object H6 extends HeadingLevel(6)
-  
-  def fromInt(n: Int): Option[HeadingLevel]
-  def unsafeFromInt(n: Int): HeadingLevel  // Throws on invalid input
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val markdown = """# My Document
+
+This is a paragraph with **bold** text.
+
+- Item 1
+- Item 2
+"""
+
+Parser.parse(markdown) match {
+  case Right(parsedDoc) => println(s"Successfully parsed ${parsedDoc.blocks.size} blocks")
+  case Left(err) => println(s"Parse error: ${err.message}")
 }
 ```
 
-**Example:**
+Round-trip verification (parse → render → parse preserves structure):
+
 ```scala
-HeadingLevel.fromInt(2)        // Some(H2)
-HeadingLevel.fromInt(7)        // None
-HeadingLevel.unsafeFromInt(3)  // H3
-HeadingLevel.H1.value          // 1
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val input = "# Hello\n\nWorld"
+// input: String = """# Hello
+// 
+// World"""
+val parsed1 = Parser.parse(input).toOption.get
+// parsed1: Doc = Doc(
+//   blocks = IndexedSeq(
+//     Heading(level = H1, content = IndexedSeq(Text("Hello"))),
+//     Paragraph(IndexedSeq(Text("World")))
+//   ),
+//   metadata = Map()
+// )
+val rendered = Renderer.render(parsed1)
+// rendered: String = """# Hello
+// World
+// 
+// """
+val parsed2 = Parser.parse(rendered).toOption.get
+// parsed2: Doc = Doc(
+//   blocks = IndexedSeq(
+//     Heading(level = H1, content = IndexedSeq(Text("Hello"))),
+//     Paragraph(IndexedSeq(Text("World")))
+//   ),
+//   metadata = Map()
+// )
+parsed1 == parsed2  // Equal after normalization
+// res5: Boolean = true
 ```
 
-### Alignment
+## Common Patterns
+
+The markdown module provides several patterns for working with documents and types. Here are the most common usage scenarios:
 
-Table column alignment:
+### String Interpolation with Compile-Time Validation
+
+The `md"..."` interpolator validates markdown at compile time and supports interpolation of any type with a `ToMarkdown` instance:
 
 ```scala
-sealed trait Alignment
-object Alignment {
-  case object None extends Alignment    // Default alignment (---)
-  case object Left extends Alignment    // Left aligned (:---)
-  case object Center extends Alignment  // Center aligned (:---:)
-  case object Right extends Alignment   // Right aligned (---:)
-}
-```
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### TableRow
+val name = "Alice"
+val count = 42
+```
 
-A row in a table:
+Now interpolate these values into markdown:
 
 ```scala
-final case class TableRow(cells: Chunk[Chunk[Inline]])
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+md"# Welcome $name\nYou have $count items."
+// res6: Doc = Doc(
+//   blocks = IndexedSeq(
+//     Heading(
+//       level = H1,
+//       content = IndexedSeq(Text("Welcome Alice\\nYou have 42 items."))
+//     )
+//   ),
+//   metadata = Map()
+// )
 ```
 
-Each cell contains a chunk of inline elements, allowing rich formatting within table cells.
+### Task Lists (GFM Feature)
+
+Task list items use `ListItem` with `checked: Option[Boolean]`:
 
-## Parsing
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### Parser.parse
+val tasks = BulletList(Chunk(
+  ListItem(Chunk(Paragraph(Chunk(Text("Buy groceries")))), Some(true)),
+  ListItem(Chunk(Paragraph(Chunk(Text("Write docs")))), Some(false)),
+  ListItem(Chunk(Paragraph(Chunk(Text("Call Alice")))), None)  // No checkbox
+), tight = true)
+```
 
-Parse a Markdown string into a `Doc`:
+Rendering the task list:
 
 ```scala
-object Parser {
-  def parse(input: String): Either[ParseError, Doc]
-}
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Renderer.render(Doc(Chunk(tasks)))
+// res7: String = """- [x] Buy groceries
+// - [ ] Write docs
+// - Call Alice
+// """
 ```
 
-**Example:**
+### Tables with Alignment
+
+Tables require a header row, alignment specification, and data rows:
+
 ```scala
+import zio.blocks.chunk.Chunk
 import zio.blocks.docs._
 
-val result = Parser.parse("# Hello\n\nThis is **bold**.")
-// Right(Doc(Chunk(
-//   Heading(H1, Chunk(Text("Hello"))),
-//   Paragraph(Chunk(Text("This is "), Strong(Chunk(Text("bold"))), Text(".")))
-// )))
+val table = Table(
+  header = TableRow(Chunk(
+    Chunk(Text("Name")),
+    Chunk(Text("Age")),
+    Chunk(Text("City"))
+  )),
+  alignments = Chunk(Alignment.Left, Alignment.Right, Alignment.Center),
+  rows = Chunk(
+    TableRow(Chunk(
+      Chunk(Text("Alice")),
+      Chunk(Text("30")),
+      Chunk(Text("NYC"))
+    )),
+    TableRow(Chunk(
+      Chunk(Text("Bob")),
+      Chunk(Text("25")),
+      Chunk(Text("LA"))
+    ))
+  )
+)
 ```
 
-### Supported Features
+Rendering the table to markdown:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-The parser supports all GitHub Flavored Markdown features:
+Renderer.render(Doc(Chunk(table)))
+// res8: String = """| Name | Age | City |
+// |:---|---:|:--:|
+// | Alice | 30 | NYC |
+// | Bob | 25 | LA |
+// """
+```
+
+### Parsing with Error Handling
 
-- **ATX headings** (# to ######)
-- **Fenced code blocks** (``` or ~~~)
-- **Thematic breaks** (---, ***, ___)
-- **Block quotes** (> prefix)
-- **Bullet and ordered lists**
-- **Task lists** (- [ ] and - [x])
-- **Tables with alignment**
-- **Inline formatting** (emphasis, strong, strikethrough, code)
-- **Links and images**
-- **Autolinks** (`<url>` or plain URLs)
-- **HTML blocks and inline HTML**
+Parser returns `Either[ParseError, Doc]` with precise location information:
 
-### Not Supported
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-- **YAML frontmatter** (causes parse error)
-- **Setext headings** (use ATX style with #)
-- **Indented code blocks** (use fenced code blocks)
-- **Link reference definitions**
+Parser.parse("# Hello\n[invalid link](") match {
+  case Right(doc) => println("Parsed successfully")
+  case Left(err) => println(s"Error at line ${err.line}, column ${err.column}: ${err.message}")
+}
+```
 
-### ParseError
+### Round-Trip Semantics
 
-Parsing error with location information:
+Parse-render-parse cycles preserve document meaning (normalized forms are equal):
 
 ```scala
-final case class ParseError(
-  message: String,
-  line: Int,        // 1-based line number
-  column: Int,      // 1-based column number
-  input: String     // The line that caused the error
-)
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val input = "# Hello\n\nWorld"
+val parsed1 = Parser.parse(input).toOption.get
+val rendered = Renderer.render(parsed1)
+val parsed2 = Parser.parse(rendered).toOption.get
+assert(parsed1 == parsed2)  // Equal after normalization
 ```
 
-**Example:**
+### Custom Type Interpolation
+
+Implement `ToMarkdown` for your types to enable interpolation:
+
 ```scala
-Parser.parse("---\ntitle: Test\n---") match {
-  case Left(err) => 
-    println(s"Error at line ${err.line}: ${err.message}")
-    // "Error at line 1: Frontmatter is not supported"
-  case Right(doc) => // Process doc
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+case class User(name: String, role: String)
+
+implicit val userToMarkdown: ToMarkdown[User] = { user =>
+  Strong(Chunk(Text(user.name), Text(s" – ${user.role}")))
 }
+
+val user = User("Alice", "Engineer")
+val doc = md"# Team\n$user"
 ```
 
-## Rendering
+Additional use cases for custom type interpolation include building documentation programmatically with rich data types, generating reports with structured business objects, and creating templates that mix markdown formatting with domain-specific data. For example, you could create instances for your API models to automatically format them as markdown tables or code examples, making it easy to generate consistent documentation from live data structures.
+
+## Integration Points
+
+The markdown module integrates seamlessly with other ZIO Blocks components to provide a cohesive ecosystem for working with structured data and documentation.
+
+**Schema Integration**: The `schema` module can derive codecs for markdown documents, enabling serialization and deserialization of `Doc` and related types. This allows you to persist markdown structures to various formats (JSON, MessagePack, BSON, etc.) while maintaining type safety and schema validation.
+
+**Chunk Integration**: Core data structures like `Doc`, `Block`, and `Inline` use `Chunk[T]` throughout for efficient immutable sequences. This provides O(1) concatenation, memory efficiency, and seamless interoperability with other ZIO libraries that also rely on chunks for data streaming and collection manipulation.
+
+**HTTP Integration**: Markdown documents can be served directly as documentation endpoints in HTTP servers. Combined with the multiple renderer options (GFM, HTML, terminal), you can build documentation APIs that serve content in multiple formats based on client preferences, making it trivial to expose living documentation alongside your application.
 
-### Markdown Rendering
+---
+
+## Doc
+
+A complete GitHub Flavored Markdown document.
+
+### Definition
 
-Render a `Doc` back to GFM Markdown:
+Here is the `Doc` type definition:
 
 ```scala
-object Renderer {
-  def render(doc: Doc): String
-  def renderBlock(block: Block): String
-  def renderInlines(inlines: Chunk[Inline]): String
-  def renderInline(inline: Inline): String
-}
+import zio.blocks.chunk.Chunk
+
+final case class Doc(blocks: Chunk[Block], metadata: Map[String, String] = Map.empty)
 ```
 
-**Example:**
+A parsed or constructed markdown document. The `metadata` field is reserved for future use and defaults to an empty map.
+
+### Construction
+
+Create an empty document:
+
 ```scala
-val doc = Parser.parse("# Title\n\nParagraph.").toOption.get
-val markdown = Renderer.render(doc)
-// "# Title\n\nParagraph.\n\n"
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val empty = Doc.empty
 ```
 
-The rendered output is GFM-compliant and can be re-parsed to produce an equivalent AST.
+Construct a document from blocks:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### HTML Rendering
+val doc = Doc(Chunk(
+  Heading(HeadingLevel.H1, Chunk(Text("Title"))),
+  Paragraph(Chunk(Text("Content")))
+))
+```
 
-Render to HTML5-compliant HTML:
+Parse a markdown string to create a document:
 
 ```scala
-object HtmlRenderer {
-  def render(doc: Doc): String         // Full HTML5 document
-  def renderFragment(doc: Doc): String // Content only, no wrapper
-  def renderBlock(block: Block): String
-  def renderInlines(inlines: Chunk[Inline]): String
-  def renderInline(inline: Inline): String
-  def escape(s: String): String        // HTML entity escaping
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Parser.parse("# Title\n\nContent") match {
+  case Right(doc) => // use doc
+  case Left(err) => // handle error
 }
 ```
 
-**Example:**
-```scala
-val doc = Parser.parse("# Hello\n\n**Bold**").toOption.get
+### Core Operations
 
-// Full document with <!DOCTYPE html>, <html>, <head>, <body>
-val fullHtml = HtmlRenderer.render(doc)
+Merge documents using concatenation with `Doc#++`:
 
-// Just the content: <h1>Hello</h1><p><strong>Bold</strong></p>
-val fragment = HtmlRenderer.renderFragment(doc)
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc1 = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Part 1")))))
+val doc2 = Doc(Chunk(Paragraph(Chunk(Text("Part 2")))))
+val combined = doc1 ++ doc2
 ```
 
-**HTML Features:**
-- Code blocks with language classes (`language-scala`, etc.)
-- Tables with proper alignment styles
-- Task list items with disabled checkboxes
-- Proper HTML entity escaping for safety
+Render a document to GFM markdown:
 
-### Terminal Rendering
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Hello")))))
+// doc: Doc = Doc(
+//   blocks = IndexedSeq(Heading(level = H1, content = IndexedSeq(Text("Hello")))),
+//   metadata = Map()
+// )
+val markdown: String = doc.toString  // Calls Renderer.render internally
+// markdown: String = """# Hello
+// """
+```
 
-Render with ANSI escape codes for colorful terminal display:
+Render to HTML with full document structure including DOCTYPE (returns complete HTML5 document with `<!DOCTYPE html>` wrapper):
 
 ```scala
-object TerminalRenderer {
-  def render(doc: Doc): String
-  def renderBlock(block: Block): String
-  def renderInlines(inlines: Chunk[Inline]): String
-  def renderInline(inline: Inline): String
-}
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Hello")))))
+// doc: Doc = Doc(
+//   blocks = IndexedSeq(Heading(level = H1, content = IndexedSeq(Text("Hello")))),
+//   metadata = Map()
+// )
+val html = doc.toHtml
+// html: String = "<!DOCTYPE html><html><head></head><body><h1>Hello</h1></body></html>"
 ```
 
-**Example:**
+Render to HTML fragment containing only the content (returns just the rendered HTML blocks without wrapper tags):
+
 ```scala
-val doc = Parser.parse("# Hello\n\nThis is **bold** and *italic*.").toOption.get
-val terminal = TerminalRenderer.render(doc)
-println(terminal)  // Displays with colors and formatting
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Hello")))))
+// doc: Doc = Doc(
+//   blocks = IndexedSeq(Heading(level = H1, content = IndexedSeq(Text("Hello")))),
+//   metadata = Map()
+// )
+val fragment = doc.toHtmlFragment
+// fragment: String = "<h1>Hello</h1>"
 ```
 
-**ANSI Styling:**
-- **Headings:** Bold + colored (H1=red, H2=yellow, H3=green, H4=cyan, H5=blue, H6=magenta)
-- **Code blocks:** Gray background
-- **Inline code:** Gray background
-- **Emphasis:** Italic
-- **Strong:** Bold
-- **Strikethrough:** Strike-through style
-- **Links:** Blue + underlined
-- **Block quotes:** Prefixed with │
+Render to colorized terminal output (returns ANSI-colored string suitable for terminal display):
 
-## String Interpolator
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### The md"..." Interpolator
+val doc = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Hello")))))
+// doc: Doc = Doc(
+//   blocks = IndexedSeq(Heading(level = H1, content = IndexedSeq(Text("Hello")))),
+//   metadata = Map()
+// )
+val terminal = doc.toTerminal
+// terminal: String = """Hello
+// 
+// """
+```
 
-Build documents with compile-time validated Markdown syntax:
+Canonicalize document structure with `Doc#normalize` to merge adjacent text nodes and remove empty blocks:
 
 ```scala
+import zio.blocks.chunk.Chunk
 import zio.blocks.docs._
 
-val name = "World"
-val greeting = md"# Hello $name"
-// Doc(Chunk(Heading(H1, Chunk(Text("Hello World")))))
+val doc = Doc(Chunk(
+  Paragraph(Chunk(Text("A"), Text("B"))),  // Adjacent text nodes
+  Paragraph(Chunk()),                      // Empty paragraph
+  Paragraph(Chunk(Text("C")))
+))
+```
 
-val items = List("one", "two", "three")
-val list = md"""
-# My List
+Call `Doc#normalize` to see the result:
 
-${items.map(i => s"- $i").mkString("\n")}
-"""
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val normalized = doc.normalize
+// normalized: Doc = Doc(
+//   blocks = IndexedSeq(
+//     Paragraph(IndexedSeq(Text("AB"))),
+//     Paragraph(IndexedSeq(Text("C")))
+//   ),
+//   metadata = Map()
+// )
 ```
 
-The interpolator:
-- **Validates syntax at compile time** - invalid markdown causes compilation error
-- **Requires ToMarkdown instances** for interpolated values
-- **Supports multi-line markdown** with triple quotes
+### Equality and Hashing
+
+Two documents are equal if their **normalized forms** are equal. This means:
 
-**Example with validation:**
 ```scala
-// This won't compile - invalid heading level
-val bad = md"####### Too many hashes"
-// Error: Invalid markdown: Invalid heading level: 7 (max is 6)
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc1 = Doc(Chunk(Paragraph(Chunk(Text("Hello"), Text(" "), Text("World")))))
+val doc2 = Doc(Chunk(Paragraph(Chunk(Text("Hello World")))))
+assert(doc1 == doc2)  // Equal after normalization
 ```
 
-### ToMarkdown Typeclass
+Hash code computes from the normalized form for consistency with `equals`.
 
-Make custom types interpolatable:
+---
+
+## Block (Sealed Trait)
+
+A block-level markdown element:
 
 ```scala
-trait ToMarkdown[-A] {
-  def toMarkdown(a: A): Inline
-}
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+sealed trait Block extends Product with Serializable
 ```
 
-**Built-in instances:**
-- `String`, `Int`, `Long`, `Double`, `Boolean` → `Text`
-- `Inline` → identity
-- `Block` → rendered to markdown then wrapped as `Text`
-- `List[A]`, `Vector[A]`, `Seq[A]`, `Chunk[A]` → comma-separated (where `A: ToMarkdown`)
+Block is a sealed trait with the following concrete subtypes.
+
+### Paragraph
+
+A paragraph containing inline content:
 
-**Custom instance example:**
 ```scala
-case class User(name: String, email: String)
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Paragraph(content: Chunk[Inline]) extends Block
+```
+
+Here's an example of creating a paragraph with mixed content:
 
-implicit val userToMarkdown: ToMarkdown[User] = user =>
-  Text(s"${user.name} <${user.email}>")
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-val user = User("Alice", "alice@example.com")
-val doc = md"Contact: $user"
-// Doc(Chunk(Paragraph(Chunk(Text("Contact: Alice <alice@example.com>")))))
+val para = Paragraph(Chunk(
+  Text("Hello "),
+  Strong(Chunk(Text("world")))
+))
 ```
 
-**Advanced example - custom formatting:**
+### Heading
+
+An ATX-style heading (# to ######) with a level and inline content:
+
 ```scala
-case class CodeSnippet(lang: String, code: String)
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-implicit val codeSnippetToMarkdown: ToMarkdown[CodeSnippet] = snippet =>
-  Text(s"```${snippet.lang}\n${snippet.code}\n```")
+final case class Heading(level: HeadingLevel, content: Chunk[Inline]) extends Block
+```
+
+Here's an example of creating headings with different levels:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-val snippet = CodeSnippet("scala", "val x = 42")
-val doc = md"Here's an example:\n\n$snippet"
+val h1 = Heading(HeadingLevel.H1, Chunk(Text("Title")))
+val h3 = Heading(HeadingLevel.H3, Chunk(Text("Subsection")))
 ```
 
-## Working with the AST
+### CodeBlock
 
-### Building Documents Programmatically
+A fenced code block with optional language/info string:
 
 ```scala
+import zio.blocks.chunk.Chunk
 import zio.blocks.docs._
+
+final case class CodeBlock(info: Option[String], code: String) extends Block
+```
+
+Here are examples of creating code blocks with and without language specification:
+
+```scala
 import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-val doc = Doc(Chunk(
-  Heading(HeadingLevel.H1, Chunk(Text("Title"))),
-  Paragraph(Chunk(
-    Text("This is "),
-    Strong(Chunk(Text("important"))),
-    Text(".")
-  )),
-  CodeBlock(Some("scala"), "val x = 42"),
-  BulletList(Chunk(
-    ListItem(Chunk(Paragraph(Chunk(Text("Item 1")))), None),
-    ListItem(Chunk(Paragraph(Chunk(Text("Done")))), Some(true)),
-    ListItem(Chunk(Paragraph(Chunk(Text("Todo")))), Some(false))
-  ), tight = true)
-))
+// Scala code block
+val scalaBlock = CodeBlock(Some("scala"), "val x = 42\nprintln(x)")
+
+// No language specified
+val plainBlock = CodeBlock(None, "some code")
 ```
 
-### Concatenation
+### ThematicBreak
 
-Combine documents with `++`:
+A thematic break (horizontal rule):
 
 ```scala
-val header = md"# Document Title"
-val body = md"Some content here."
-val footer = md"---\n*Footer*"
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-val full = header ++ body ++ footer
+case object ThematicBreak extends Block
 ```
 
-**Metadata merging:**
+Create a thematic break:
+
 ```scala
-val doc1 = Doc(Chunk(Paragraph(Chunk(Text("A")))), Map("author" -> "Alice"))
-val doc2 = Doc(Chunk(Paragraph(Chunk(Text("B")))), Map("version" -> "1.0"))
-val combined = doc1 ++ doc2
-// combined.metadata == Map("author" -> "Alice", "version" -> "1.0")
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val break = ThematicBreak
 ```
 
-### Normalization
+**Renders as:** `---\n` (or `***` or `___`)
+
+### BlockQuote
 
-`normalize` cleans up the AST:
-- Merges adjacent `Text` nodes
-- Removes empty paragraphs and other empty blocks
-- Recursively normalizes nested structures (lists, block quotes, tables)
+A block quote containing nested blocks:
 
 ```scala
-val messy = Doc(Chunk(
-  Paragraph(Chunk(
-    Text("Hello "),
-    Text("World")  // Adjacent Text nodes
-  )),
-  Paragraph(Chunk.empty)  // Empty paragraph
-))
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-val clean = messy.normalize
-// Doc(Chunk(Paragraph(Chunk(Text("Hello World")))))
+final case class BlockQuote(content: Chunk[Block]) extends Block
 ```
 
-**When to normalize:**
-- Before comparing documents for equality (equality uses normalized form)
-- After programmatic AST construction with potential duplicates
-- When cleaning up parsed or generated content
+Here's an example of creating a block quote:
 
-**Note:** `Doc.equals` automatically normalizes both sides, so explicit normalization isn't needed for equality checks.
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-## Advanced Usage
+val quote = BlockQuote(Chunk(
+  Paragraph(Chunk(Text("This is a famous quote.")))
+))
+```
 
-### Custom Renderers
+### BulletList
 
-You can traverse the AST to create custom renderers:
+An unordered list with bullet markers (-, *, +):
 
 ```scala
-def customRender(doc: Doc): String = {
-  doc.blocks.map {
-    case Heading(level, content) => 
-      s"${"=" * level.value} ${renderInlines(content)}\n"
-    case Paragraph(content) => 
-      renderInlines(content) + "\n\n"
-    case _ => 
-      Renderer.renderBlock(_)
-  }.mkString
-}
-```
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### Extracting Information
+final case class BulletList(items: Chunk[ListItem], tight: Boolean) extends Block
+```
 
-Pattern match on the AST to extract structured data:
+The `tight` parameter controls spacing: `true` removes blank lines between items for compact rendering. Here's an example:
 
 ```scala
-def extractHeadings(doc: Doc): List[(Int, String)] = {
-  doc.blocks.collect {
-    case Heading(level, content) =>
-      (level.value, Renderer.renderInlines(content))
-  }.toList
-}
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-def extractLinks(doc: Doc): List[String] = {
-  def findLinksInInlines(inlines: Chunk[Inline]): List[String] = {
-    inlines.toList.flatMap {
-      case Link(_, url, _) => List(url)
-      case Strong(content) => findLinksInInlines(content)
-      case Emphasis(content) => findLinksInInlines(content)
-      case _ => Nil
-    }
-  }
-  
-  doc.blocks.flatMap {
-    case Paragraph(content) => findLinksInInlines(content)
-    case Heading(_, content) => findLinksInInlines(content)
-    case _ => Nil
-  }.toList
-}
+val list = BulletList(Chunk(
+  ListItem(Chunk(Paragraph(Chunk(Text("Item 1")))), None),
+  ListItem(Chunk(Paragraph(Chunk(Text("Item 2")))), None)
+), tight = true)
 ```
 
-### Transforming Documents
+### OrderedList
 
-Apply transformations to the AST:
+An ordered list with numeric markers (1., 2., etc.):
 
 ```scala
-def uppercaseHeadings(doc: Doc): Doc = {
-  val transformedBlocks = doc.blocks.map {
-    case Heading(level, content) =>
-      val upperContent = content.map {
-        case Text(value) => Text(value.toUpperCase)
-        case other => other
-      }
-      Heading(level, upperContent)
-    case other => other
-  }
-  Doc(transformedBlocks, doc.metadata)
-}
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class OrderedList(start: Int, items: Chunk[ListItem], tight: Boolean) extends Block
 ```
 
-## Best Practices
+The `start` parameter specifies the starting number (typically 1). Here's an example:
 
-### Parsing
-- Always handle `Either[ParseError, Doc]` - don't assume parsing succeeds
-- For user input, display parse errors with line/column information
-- Use the interpolator for static markdown (compile-time validation)
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
 
-### Building
-- Prefer the `md"..."` interpolator for compile-time safety
-- Use programmatic construction for dynamic content
-- Call `normalize` after complex programmatic construction
+val list = OrderedList(
+  start = 1,
+  items = Chunk(
+    ListItem(Chunk(Paragraph(Chunk(Text("First")))), None),
+    ListItem(Chunk(Paragraph(Chunk(Text("Second")))), None)
+  ),
+  tight = true
+)
+```
+
+### ListItem
+
+A list item, optionally a task list item:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class ListItem(content: Chunk[Block], checked: Option[Boolean]) extends Block
+```
+
+The `checked` parameter: `Some(true)` renders as `[x]`, `Some(false)` renders as `[ ]`, `None` for regular list items. Here are examples of each type:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+// Regular list item
+val item = ListItem(Chunk(Paragraph(Chunk(Text("Task")))), None)
+
+// Completed task
+val completed = ListItem(Chunk(Paragraph(Chunk(Text("Done")))), Some(true))
+
+// Incomplete task
+val incomplete = ListItem(Chunk(Paragraph(Chunk(Text("TODO")))), Some(false))
+```
+
+### HtmlBlock
+
+Raw HTML block content:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class HtmlBlock(content: String) extends Block
+```
+
+Here's an example of creating an HTML block:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val html = HtmlBlock("<div class='alert'>Custom HTML</div>")
+```
+
+### Table
+
+A GitHub Flavored Markdown table with aligned columns:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Table(header: TableRow, alignments: Chunk[Alignment], rows: Chunk[TableRow]) extends Block
+```
+
+Here's an example of creating a table:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val table = Table(
+  header = TableRow(Chunk(Chunk(Text("Name")), Chunk(Text("Age")))),
+  alignments = Chunk(Alignment.Left, Alignment.Right),
+  rows = Chunk(
+    TableRow(Chunk(Chunk(Text("Alice")), Chunk(Text("30")))),
+    TableRow(Chunk(Chunk(Text("Bob")), Chunk(Text("25"))))
+  )
+)
+```
+
+---
+
+## Inline (Sealed Trait)
+
+An inline-level markdown element:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+sealed trait Inline extends Product with Serializable
+```
+
+Inline is a sealed trait with concrete subtypes, defining both object-level and top-level forms for API compatibility.
+
+### Text
+
+Plain text content:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Text(value: String) extends Inline
+```
+
+Here's an example of creating text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val text = Text("Hello world")
+```
+
+### Code
+
+Inline code span (backtick-delimited):
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Code(value: String) extends Inline
+```
+
+Here's an example of creating inline code:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val code = Code("val x = 42")
+```
+
+### Emphasis
+
+Emphasized (italic) text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Emphasis(content: Chunk[Inline]) extends Inline
+```
+
+Here's an example of creating emphasized text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val emphasis = Emphasis(Chunk(Text("italic")))
+// Renders as: *italic*
+```
+
+### Strong
+
+Strong (bold) text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Strong(content: Chunk[Inline]) extends Inline
+```
+
+Here's an example of creating strong text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val strong = Strong(Chunk(Text("bold")))
+// Renders as: **bold**
+```
+
+### Strikethrough
+
+Strikethrough text (GFM feature):
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Strikethrough(content: Chunk[Inline]) extends Inline
+```
+
+Here's an example of creating strikethrough text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val struck = Strikethrough(Chunk(Text("deprecated")))
+// Renders as: ~~deprecated~~
+```
+
+### Link
+
+A hyperlink:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Link(text: Chunk[Inline], url: String, title: Option[String]) extends Inline
+```
+
+The `title` parameter is optional link title text. Here are examples of creating links:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+// Simple link
+val link = Link(Chunk(Text("Click here")), "https://example.com", None)
+
+// Link with title
+val titled = Link(Chunk(Text("Docs")), "/docs", Some("Documentation"))
+```
+
+### Image
+
+An image reference:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Image(alt: String, url: String, title: Option[String]) extends Inline
+```
+
+Here are examples of creating images:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val img = Image(alt = "Logo", url = "/logo.png", None)
+val imgWithTitle = Image(alt = "Icon", url = "/icon.svg", Some("App Icon"))
+```
+
+### HtmlInline
+
+Raw HTML inline content:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class HtmlInline(content: String) extends Inline
+```
+
+Here's an example of creating HTML inline content:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val html = HtmlInline("<span class='highlight'>custom</span>")
+```
+
+### SoftBreak
+
+A soft line break (single newline, rendered as space or newline depending on context):
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+case object SoftBreak extends Inline
+```
+
+### HardBreak
+
+A hard line break (two spaces or backslash before newline):
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+case object HardBreak extends Inline
+```
+
+### Autolink
+
+An autolink (URL or email in angle brackets):
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class Autolink(url: String, isEmail: Boolean) extends Inline
+```
+
+Here are examples of creating autolinks:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val urlLink = Autolink("https://example.com", isEmail = false)
+val emailLink = Autolink("user@example.com", isEmail = true)
+// Renders as: <https://example.com> and <user@example.com>
+```
+
+---
+
+## HeadingLevel
+
+Heading levels from H1 to H6:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+sealed abstract class HeadingLevel(val value: Int) extends Product with Serializable
+
+object HeadingLevel {
+  case object H1 extends HeadingLevel(1)
+  case object H2 extends HeadingLevel(2)
+  case object H3 extends HeadingLevel(3)
+  case object H4 extends HeadingLevel(4)
+  case object H5 extends HeadingLevel(5)
+  case object H6 extends HeadingLevel(6)
+}
+```
+
+### Safe Construction
+
+Construct a heading level from an integer, returning an `Option`:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+HeadingLevel.fromInt(2) == Some(HeadingLevel.H2)
+HeadingLevel.fromInt(7) == None  // Out of range
+```
+
+Construct a heading level unsafely, throwing if input is invalid:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+HeadingLevel.unsafeFromInt(3)  // HeadingLevel.H3
+HeadingLevel.unsafeFromInt(7)  // Throws IllegalArgumentException
+```
+
+### Accessing Value
+
+Access the numeric value of a heading level:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+HeadingLevel.H1.value == 1
+```
+
+---
+
+## Alignment
+
+Table column alignment specification:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+sealed trait Alignment extends Product with Serializable
+
+object Alignment {
+  case object Left   extends Alignment
+  case object Right  extends Alignment
+  case object Center extends Alignment
+  case object None   extends Alignment
+}
+```
+
+### Predefined Alignments
+
+Use predefined alignment values for table columns:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Alignment.Left    // Renders as :---
+Alignment.Right   // Renders as ---:
+Alignment.Center  // Renders as :---:
+Alignment.None    // Renders as ---
+```
+
+### Use in Tables
+
+Create a table with specific column alignments:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+val header = TableRow(Chunk(
+  Chunk(Text("Name")),
+  Chunk(Text("Age")),
+  Chunk(Text("City"))
+))
+val rows = Chunk(
+  TableRow(Chunk(
+    Chunk(Text("Alice")),
+    Chunk(Text("30")),
+    Chunk(Text("NYC"))
+  )),
+  TableRow(Chunk(
+    Chunk(Text("Bob")),
+    Chunk(Text("25")),
+    Chunk(Text("LA"))
+  ))
+)
+val alignments = Chunk(Alignment.Left, Alignment.Center, Alignment.Right)
+val table = Table(header, alignments, rows)
+val doc = Doc(Chunk(table))
+```
+
+If we render this document, the table will have left-aligned "Name", center-aligned "Age", and right-aligned "City":
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Renderer.render(doc)
+// res45: String = """| Name | Age | City |
+// |:---|:--:|---:|
+// | Alice | 30 | NYC |
+// | Bob | 25 | LA |
+// """
+```
+
+---
+
+## TableRow
+
+A single row in a table, containing cells as inline content:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class TableRow(cells: Chunk[Chunk[Inline]])
+```
+
+Each cell is a `Chunk[Inline]`, allowing formatted content (text, links, emphasis, etc.). Here's an example:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val row = TableRow(Chunk(
+  Chunk(Text("Alice")),
+  Chunk(Strong(Chunk(Text("30")))),
+  Chunk(Link(Chunk(Text("NYC")), "/cities/nyc", None))
+))
+```
+
+---
+
+## Parser
+
+A singleton object providing strict GitHub Flavored Markdown parsing with position-aware error reporting.
+
+### Parsing
+
+Use the main entry point to parse markdown:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Parser.parse(input: String): Either[ParseError, Doc]
+```
+
+Returns `Right(doc)` on success or `Left(error)` on parse failure. Here's an example:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val result = Parser.parse("# Hello\n\nWorld")
+result match {
+  case Right(doc) => println(s"Parsed ${doc.blocks.size} blocks")
+  case Left(err) => println(s"Parse error at line ${err.line}: ${err.message}")
+}
+```
+
+### Supported Features
+
+- ATX headings (# to ######)
+- Fenced code blocks (``` or ~~~)
+- Thematic breaks (---, ***, ___)
+- Block quotes (> prefix)
+- Bullet lists (-, *, +)
+- Ordered lists (1., 2., etc.)
+- Task lists (- [ ] and - [x])
+- Tables with alignment (GFM)
+- Inline formatting (emphasis, strong, strikethrough)
+- Links and images with optional titles
+- Autolinks (`<url>` or `<email>`)
+- HTML blocks and inline HTML
+- Soft and hard line breaks
+
+### Unsupported Features
+
+- YAML frontmatter (causes parse error)
+- Setext headings (use ATX style with # instead)
+- Indented code blocks (use fenced with ``` instead)
+- Link reference definitions
+
+---
+
+## ParseError
+
+Error information from parsing, with precise location data:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+final case class ParseError(
+  message: String,    // Human-readable error description
+  line: Int,          // 1-based line number
+  column: Int,        // 1-based column number
+  input: String       // The line that caused the error
+)
+```
+
+Here's an example of creating a `ParseError`:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val err = ParseError("Unexpected token", line = 5, column = 12, input = "[invalid markdown]")
+```
+
+Get the string representation of the error:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+err.toString
+// res48: String = """ParseError at line 5, column 12: Unexpected token
+//   [invalid markdown]"""
+```
+
+---
+
+## Renderer
+
+A singleton object that renders markdown documents back to GitHub Flavored Markdown string format:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+object Renderer
+```
+
+### Rendering
+
+Render an entire document to GFM markdown:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Renderer.render(doc: Doc): String
+```
+
+Here's an example of rendering a document:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = Doc(Chunk(
+  Heading(HeadingLevel.H1, Chunk(Text("Title"))),
+  Paragraph(Chunk(Text("Content")))
+))
+val rendered = Renderer.render(doc)
+```
+
+The result:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+rendered
+// res50: String = """# Title
+// Content
+// 
+// """
+```
+
+Render individual blocks:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Renderer.renderBlock(block: Block): String
+```
+
+Render inline content:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+Renderer.renderInlines(inlines: Chunk[Inline]): String
+Renderer.renderInline(inline: Inline): String
+```
+
+### Normalization During Rendering
+
+The renderer does not normalize; use `doc.normalize` before rendering if normalization is needed.
+
+### Round-Trip Semantics
+
+Re-parse rendered output to verify round-trip semantics:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val original = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Title")))))
+val markdown = Renderer.render(original)
+val reparsed = Parser.parse(markdown).toOption.get
+assert(original == reparsed)  // Equal after normalization
+```
+
+---
+
+## HtmlRenderer
+
+A singleton object that renders markdown documents to HTML5:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+object HtmlRenderer
+```
+
+### Full Document Rendering
+
+Render a document as complete HTML with DOCTYPE and html wrapper tags:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+HtmlRenderer.render(doc: Doc): String
+```
+
+Here's an example of rendering a complete HTML document:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Title")))))
+val html = HtmlRenderer.render(doc)
+```
+
+The result:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+html
+// res54: String = "<!DOCTYPE html><html><head></head><body><h1>Title</h1></body></html>"
+```
+
+### Fragment Rendering
+
+Render content-only HTML without wrapper tags:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+HtmlRenderer.renderFragment(doc: Doc): String
+```
+
+Here's an example of rendering an HTML fragment:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val fragment = HtmlRenderer.renderFragment(doc)
+```
+
+Use fragments to embed markdown content into existing HTML templates.
+
+### HTML Feature Mapping
+
+- Headings → `<h1>` through `<h6>`
+- Paragraphs → `<p>`
+- Code blocks → `<pre><code class="language-...">` (language from info string)
+- Thematic breaks → `<hr>`
+- Block quotes → `<blockquote>`
+- Lists → `<ul>` and `<ol>` with `<li>`
+- Task lists → `<li>` with checkbox-like rendering
+- Tables → `<table>`, `<tr>`, `<td>` with alignment classes
+- Inline code → `<code>`
+- Emphasis → `<em>`
+- Strong → `<strong>`
+- Strikethrough → `<del>` or `<s>`
+- Links → `<a href="...">`
+- Images → `<img alt="..." src="...">`
+- HTML blocks and inlines → pass through as-is
+
+---
+
+## TerminalRenderer
+
+A singleton object that renders markdown to ANSI-colored terminal output optimized for console display:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+object TerminalRenderer
+```
 
 ### Rendering
-- Use `toHtmlFragment` when embedding in existing HTML pages
-- Use `render` (full HTML) for standalone documents
-- Use `toTerminal` for CLI tools and REPLs
-- Use `toString` when you need markdown output
-
-### Performance
-- Parse once, render multiple times if possible
-- Normalization is not free - don't call it unnecessarily
-- The AST is immutable - transformations create new instances
+
+Render a document to ANSI-colored terminal output:
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+TerminalRenderer.render(doc: Doc): String
+```
+
+Here's an example of rendering to terminal:
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = Doc(Chunk(Heading(HeadingLevel.H1, Chunk(Text("Title")))))
+val terminal = TerminalRenderer.render(doc)
+// Returns ANSI-colored string: Title\n\n
+```
+
+### Color Scheme
+
+Headings use different colors by level:
+- H1 → Red
+- H2 → Yellow
+- H3 → Green
+- H4 → Cyan
+- H5 → Blue
+- H6 → Magenta
+
+Inline elements use ANSI styles:
+- Strong/Bold → ANSI bold
+- Emphasis/Italic → ANSI italic
+- Code → Gray background
+- Links → Underlined
+- Strikethrough → ANSI strikethrough style
+
+The output is designed to be readable on both light and dark terminal backgrounds.
+
+---
+
+## ToMarkdown
+
+Type class for converting Scala values to markdown inline elements, enabling interpolation in the `md"..."` string interpolator.
+
+### Definition
+
+Define the `ToMarkdown` type class:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+trait ToMarkdown[-A] {
+  def toMarkdown(a: A): Inline
+}
+```
+
+The type parameter is contravariant (`-A`), allowing subtypes to use supertype instances.
+
+### Summon an Instance
+
+Summon a ToMarkdown instance:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+ToMarkdown[String]  // Implicitly summons the ToMarkdown[String] instance
+```
+
+### Built-In Instances
+
+Convert primitive types to plain text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+ToMarkdown[String]    // a: String => Text(a)
+ToMarkdown[Int]       // a: Int => Text(a.toString)
+ToMarkdown[Long]      // a: Long => Text(a.toString)
+ToMarkdown[Double]    // a: Double => Text(a.toString)
+ToMarkdown[Boolean]   // a: Boolean => Text(a.toString)
+```
+
+Pass inline elements through unchanged:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+ToMarkdown[Inline]    // a: Inline => a (identity)
+```
+
+Convert collections to comma-separated text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+ToMarkdown[List[A]]    // as: List[A] => Text(as.map(...).mkString(", "))
+ToMarkdown[Chunk[A]]   // as: Chunk[A] => Text(as.map(...).mkString(", "))
+ToMarkdown[Vector[A]]  // as: Vector[A] => Text(as.map(...).mkString(", "))
+ToMarkdown[Seq[A]]     // as: Seq[A] => Text(as.map(...).mkString(", "))
+```
+
+For collection instances, each element is converted using its `ToMarkdown[A]` instance, then joined with ", ".
+
+Render blocks to markdown text:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+ToMarkdown[Block]     // b: Block => Text(Renderer.render(Doc(Chunk(b))).trim)
+```
+
+### Custom Implementations
+
+Define custom `ToMarkdown` instances for your types:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+case class Person(name: String, age: Int)
+
+implicit val personToMarkdown: ToMarkdown[Person] = { person =>
+  Strong(Chunk(Text(person.name)))
+}
+
+val p = Person("Alice", 30)
+val doc = md"## User: $p"  // Interpolates as strong text "Alice"
+```
+
+---
+
+## String Interpolator (`md"..."`)
+
+The `md` string interpolator validates markdown at compile time and supports runtime interpolation of values.
+
+### Compile-Time Validation
+
+Markdown syntax inside `md"..."` is validated at compile time:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val doc = md"# Valid heading"  // Compiles
+
+val invalid = md"# [unclosed link]("  // Compile error: Invalid markdown
+```
+
+### Runtime Interpolation
+
+Values are interpolated and converted to inline markdown using `ToMarkdown`:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+val name = "Alice"
+val count = 42
+val doc = md"""
+# Welcome $name
+
+You have $count items.
+"""
+// Equivalent to parsing: "# Welcome Alice\n\nYou have 42 items."
+```
+
+### Custom Type Interpolation
+
+Any type with a `ToMarkdown` instance can be interpolated:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs._
+
+case class Tag(label: String)
+implicit val tagToMarkdown: ToMarkdown[Tag] = tag =>
+  Code(tag.label)
+
+val tag = Tag("important")
+val doc = md"Please review: $tag"  // Renders tag as inline code
+```
+
+### Interpolation Mechanics
+
+The interpolator:
+1. Collects string parts and interpolated values (as `Inline` elements via `ToMarkdown`)
+2. Combines parts and rendered inlines into a markdown string
+3. Parses the combined string at runtime
+4. Returns a `Doc` or throws `IllegalArgumentException` if parsing fails