# Hiccup → Typst Mapping Reference

## Audit of Current Tags

### ✅ Valid - Direct Typst Functions

| Hiccup | Typst | Notes |
|--------|-------|-------|
| `[:heading {:level 2} "Text"]` | `#heading(level: 2)[Text]` | ✅ Works |
| `[:strong "text"]` | `#strong[text]` | ✅ Works |
| `[:emph "text"]` | `#emph[text]` | ✅ Works |
| `[:link {:dest "url"} "text"]` | `#link("url")[text]` | ✅ Works |
| `[:image {:width "50%"} "path.png"]` | `#image("path.png", width: 50%)` | ✅ Works |
| `[:block {:inset "1em"} ...]` | `#block(inset: 1em)[...]` | ✅ Works |
| `[:bibliography "refs.bib"]` | `#bibliography("refs.bib")` | ✅ Works |

### ❌ Invalid - Don't Exist in Typst

| Bad Hiccup | Problem | Fix |
|------------|---------|-----|
| `[:p "text"]` | No paragraph function | Just use strings, paragraphs are implicit |
| `[:item "text"]` | Not a function | Items are args to `list()` |
| `[:cell "text"]` | Not a function | Cells are args to `table()` |
| `[:div ...]` | HTML, not Typst | Use `[:block ...]` |
| `[:span ...]` | HTML, not Typst | Just inline content, or `[:box ...]` |
| `[:aside ...]` | Doesn't exist | Use `[:block ...]` with styling |
| `[:section ...]` | Doesn't exist | Just use headings |
| `[:doc ...]` | Doesn't exist | Top-level is just content |
| `[:table-row ...]` | Doesn't exist | Tables are flat |

### ⚠️ Needs Adjustment

| Current | Problem | Correct |
|---------|---------|---------|
| `[:linebreak]` | Function name | `[:linebreak]` → `#linebreak()` ✅ actually works |
| `[:h-space "2em"]` | Wrong name | `[:h "2em"]` → `#h(2em)` |
| `[:figure [:image ...] [:caption ...]]` | Caption isn't a child | See below |
| `[:math "x^2"]` | Need to distinguish inline/block | `$x^2$` vs `$ x^2 $` |
| `[:code {:lang "py"} "..."]` | Function is `raw` | `#raw(lang: "python", "...")` |
| `[:ref :label]` | Takes label not string | `#ref(<label>)` |
| `[:cite :key]` | Takes label | `#cite(<key>)` |

## Corrected Mappings

### Lists

Typst `list` takes content blocks as positional args, not `:item` children:

```clojure
;; OLD (wrong)
[:list
  [:item "First"]
  [:item "Second"]]

;; NEW (correct)
[:list "First" "Second"]
;; => #list([First], [Second])

;; With formatted items
[:list
  [:strong "Important"]
  "Regular item"]
;; => #list([#strong[Important]], [Regular item])

;; Nested
[:list
  "Top level"
  [:list "Nested 1" "Nested 2"]]
```

**Typst output:**
```typst
#list(
  [First],
  [Second],
)
```

### Tables

Same pattern - cells are positional args:

```clojure
;; OLD (wrong)
[:table {:columns 2}
  [:cell "A"] [:cell "B"]
  [:cell "1"] [:cell "2"]]

;; NEW (correct)
[:table {:columns 2}
  "A" "B"
  "1" "2"]
;; => #table(columns: 2, [A], [B], [1], [2])

;; With formatting
[:table {:columns 2}
  [:strong "Header 1"] [:strong "Header 2"]
  "Data 1" "Data 2"]
```

**Typst output:**
```typst
#table(
  columns: 2,
  [#strong[Header 1]], [#strong[Header 2]],
  [Data 1], [Data 2],
)
```

### Figures

Caption is a named parameter, not a child element:

```clojure
;; OLD (wrong)
[:figure
  [:image "arch.png"]
  [:caption "Architecture diagram"]]

;; NEW (correct)
[:figure {:caption "Architecture diagram"}
  [:image "arch.png"]]
;; => #figure(image("arch.png"), caption: [Architecture diagram])

;; With label for referencing
[:figure {:caption "Architecture" :label :fig:arch}
  [:image {:width "80%"} "arch.png"]]
;; => #figure(image("arch.png", width: 80%), caption: [Architecture]) <fig:arch>
```

**Typst output:**
```typst
#figure(
  image("arch.png", width: 80%),
  caption: [Architecture],
) <fig:arch>
```

### Math

```clojure
;; Inline math
[:$ "x^2 + y^2"]
;; => $x^2 + y^2$

;; Block/display math
[:$$ "sum_(i=0)^n i"]
;; => $ sum_(i=0)^n i $

;; Or with explicit flag
[:math "x^2"]           ;; inline by default
[:math {:block true} "sum_(i=0)^n i"]
```

### Code/Raw

```clojure
;; Inline code
[:raw "let x = 1"]
;; => `let x = 1`

;; Code block with language
[:raw {:lang "python" :block true} "print('hello')"]
;; => ```python
;;    print('hello')
;;    ```
```

**Typst output:**
```typst
#raw("let x = 1")
#raw(lang: "python", block: true, "print('hello')")
```

### References and Citations

```clojure
;; Reference a label
[:ref :fig:arch]
;; => @fig:arch

;; Citation
[:cite :smith2020]
;; => @smith2020

;; Multiple citations
[:cite :smith2020 :jones2021]
;; => @smith2020 @jones2021
```

### Horizontal/Vertical Space

```clojure
[:h "2em"]    ;; => #h(2em)
[:v "1em"]    ;; => #v(1em)
```

### Page/Document Settings

`set` rules are special - they affect following content:

```clojure
;; Set rules (affects everything after)
[:set :page {:paper "a4" :margin "2cm"}]
;; => #set page(paper: "a4", margin: 2cm)

[:set :text {:font "New Computer Modern" :size "11pt"}]
;; => #set text(font: "New Computer Modern", size: 11pt)

;; Show rules
[:show :heading {:set {:text {:fill "blue"}}}]
;; => #show heading: set text(fill: blue)
```

### Paragraphs

There is no paragraph function. Paragraphs are created by blank lines:

```clojure
;; Just strings, separated by [:parbreak] or blank content
"First paragraph."
[:parbreak]
"Second paragraph."

;; Or in raw mode, just write naturally
#t"
First paragraph.

Second paragraph.
"
```

## Revised Full Example

```clojure
(def my-doc
  [;; Set rules at top
   [:set :page {:paper "a4"}]
   [:set :text {:font "Linux Libertine"}]

   [:heading {:level 1} "My Paper"]

   "This is the introduction. We discuss "
   [:emph "important things"] "."

   [:parbreak]

   [:heading {:level 2} "Methods"]

   "We used the following approach:"

   [:list
     "Step one"
     "Step two"
     [:strong "Step three (important)"]]

   [:heading {:level 2} "Results"]

   "See " [:ref :fig:results] " and " [:ref :tab:data] "."

   [:figure {:caption "Results visualization" :label :fig:results}
     [:image {:width "80%"} "results.png"]]

   [:table {:columns 2 :label :tab:data}
     [:strong "Input"] [:strong "Output"]
     "1" "1"
     "2" "4"
     "3" "9"]

   "The equation is " [:$ "E = mc^2"] "."

   [:$$ "integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2"]

   [:bibliography "refs.bib"]])
```

**Compiles to:**

```typst
#set page(paper: "a4")
#set text(font: "Linux Libertine")

#heading(level: 1)[My Paper]

This is the introduction. We discuss #emph[important things].

#heading(level: 2)[Methods]

We used the following approach:

#list(
  [Step one],
  [Step two],
  [#strong[Step three (important)]],
)

#heading(level: 2)[Results]

See @fig:results and @tab:data.

#figure(
  image("results.png", width: 80%),
  caption: [Results visualization],
) <fig:results>

#table(
  columns: 2,
  [#strong[Input]], [#strong[Output]],
  [1], [1],
  [2], [4],
  [3], [9],
) <tab:data>

The equation is $E = mc^2$.

$ integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2 $

#bibliography("refs.bib")
```

## Summary of Changes

1. **Removed**: `:p`, `:item`, `:cell`, `:div`, `:span`, `:aside`, `:section`, `:doc`
2. **Lists/Tables**: Children are direct content, not wrapped in `:item`/`:cell`
3. **Figures**: Caption is an attribute, not a child
4. **Math**: Use `:$` for inline, `:$$` for block
5. **Code**: Use `:raw` not `:code`
6. **Space**: Use `:h`/`:v` not `:h-space`
7. **Settings**: `:set` takes element type and attrs
8. **Paragraphs**: Use `:parbreak` or just content flow