Commitdba1f70aRecorded19 Feb 2026Repositorysigil-sxml

docs: Add package documentation for sigil-sxml, sigil-css, and sigil-web

Changed
 docs/sxml.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
Diff
docs/sxml.mdadded
@@ -0,0 +1,152 @@
+1
# SXML
+2
+3
> SXML representation and HTML/XML serialization.
+4
+5
```scheme
+6
(import (sigil sxml))
+7
```
+8
+9
## SXML Format
+10
+11
SXML is an S-expression representation of XML/HTML documents. Elements are lists starting with a tag symbol, with optional attributes in an `(@)` form.
+12
+13
| Form | Description |
+14
|------|-------------|
+15
| `(tag content ...)` | Element with content |
+16
| `(tag (@ (attr val) ...) content ...)` | Element with attributes |
+17
| `"text"` | Text content |
+18
| `(*raw* "html")` | Raw HTML (no escaping) |
+19
| `(document content ...)` | Document wrapper (stripped on output) |
+20
+21
```scheme
+22
;; Simple element
+23
'(p "Hello, world!")
+24
+25
;; Element with attributes
+26
'(div (@ (class "main") (id "content")) "Hello")
+27
+28
;; Nested elements
+29
'(ul (li "One") (li "Two") (li "Three"))
+30
```
+31
+32
## sxml->html
+33
+34
Convert an SXML tree to an HTML string. Void elements like `<br>` and `<img>` are output without a closing slash. Content inside `<style>` and `<script>` tags is not escaped.
+35
+36
```scheme
+37
(sxml->html '(p "Hello"))
+38
; => "<p>Hello</p>"
+39
+40
(sxml->html '(div (@ (class "main")) (p "text")))
+41
; => "<div class=\"main\"><p>text</p></div>"
+42
+43
;; Void elements use HTML style (no closing slash)
+44
(sxml->html '(br))
+45
; => "<br>"
+46
+47
(sxml->html '(img (@ (src "photo.jpg"))))
+48
; => "<img src=\"photo.jpg\">"
+49
+50
;; Document wrapper is stripped
+51
(sxml->html '(document (p "From markdown")))
+52
; => "<p>From markdown</p>"
+53
```
+54
+55
## sxml->xml
+56
+57
Convert an SXML tree to an XML string. Void elements use self-closing syntax with ` />`.
+58
+59
```scheme
+60
(sxml->xml '(item (@ (id "1")) "Content"))
+61
; => "<item id=\"1\">Content</item>"
+62
+63
;; Void elements use XML style
+64
(sxml->xml '(img (@ (src "photo.jpg"))))
+65
; => "<img src=\"photo.jpg\" />"
+66
```
+67
+68
## xml-escape
+69
+70
Escape special XML characters (`&`, `<`, `>`, `"`, `'`) in text.
+71
+72
```scheme
+73
(xml-escape "Tom & Jerry") ; => "Tom &amp; Jerry"
+74
(xml-escape "<script>") ; => "&lt;script&gt;"
+75
(xml-escape "She said \"hi\"") ; => "She said &quot;hi&quot;"
+76
```
+77
+78
## Element Inspection
+79
+80
Examine the structure of SXML elements.
+81
+82
```scheme
+83
(sxml-element? '(div "hello")) ; => #t
+84
(sxml-element? "text") ; => #f
+85
+86
(sxml-tag '(div (@ (class "box")) "content"))
+87
; => div
+88
+89
(sxml-attributes '(div (@ (id "main") (class "box")) "text"))
+90
; => ((id "main") (class "box"))
+91
+92
(sxml-attributes '(p "text"))
+93
; => ()
+94
+95
(sxml-content '(div (@ (id "main")) "hello" " " "world"))
+96
; => ("hello" " " "world")
+97
```
+98
+99
## Attribute Utilities
+100
+101
Look up or modify attributes on SXML elements.
+102
+103
```scheme
+104
;; Get attribute value
+105
(sxml-attr-ref '(div (@ (id "main"))) 'id) ; => "main"
+106
(sxml-attr-ref '(div (@ (id "main"))) 'class) ; => #f
+107
+108
;; Set attribute (returns new element)
+109
(sxml-attr-set '(div "text") 'id "main")
+110
; => (div (@ (id "main")) "text")
+111
+112
(sxml-attr-set '(div (@ (id "old"))) 'id "new")
+113
; => (div (@ (id "new")))
+114
```
+115
+116
## Common Patterns
+117
+118
### Building a Page
+119
+120
```scheme
+121
(import (sigil sxml))
+122
+123
(define (page title body)
+124
`(html
+125
(head (title ,title))
+126
(body ,@body)))
+127
+128
(sxml->html
+129
(page "My Site"
+130
(list
+131
'(h1 "Welcome")
+132
'(p "Hello, world!"))))
+133
```
+134
+135
### Raw HTML Content
+136
+137
Use `*raw*` to embed pre-rendered HTML without escaping:
+138
+139
```scheme
+140
(sxml->html
+141
`(div (@ (class "content"))
+142
(*raw* "<strong>Already formatted</strong>")))
+143
; => "<div class=\"content\"><strong>Already formatted</strong></div>"
+144
```
+145
+146
### Inline Styles
+147
+148
```scheme
+149
(sxml->html
+150
`(style (*raw* ,(css->string
+151
(css ".container" (max-width "800px"))))))
+152
```