readme

pimbrouwers · pimbrouwers · commit 22fb6c12e850 · 2025-09-10T07:05:53.000-04:00
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -3,6 +3,10 @@ name: build
 on:
   push:
     branches: [master]
+    # exclude commits
+    paths-ignore:
+      - 'README.md'
+
   pull_request:
 
 jobs:
@@ -26,4 +30,4 @@ jobs:
         run: dotnet build src/Falco.Markup -c Release
 
       - name: Test
-        run: dotnet test test/Falco.Markup.Tests -c Release
+        run: dotnet test test/Falco.Markup.Tests -c Release
diff --git a/README.md b/README.md
@@ -337,10 +337,22 @@ let xmlDoc =
 let xml = renderXml xmlDoc
 ```
 
-## HTML Fragments
+## Template Fragments
 
-Sometimes you may want to create a fragment of HTML, without the surrounding `<html>`, `<head>` and `<body>` tags. Or, any wrapper element for that matter.
+There are circumstances where you may want to render only a portion of your view. Especially common in [hypermedia driven](https://htmx.org/essays/hypermedia-driven-applications/) applications. Supporting [template fragments](https://htmx.org/essays/template-fragments/) is helpful in maintaining locality of behaviour, because it allows you to decompose a particular view for partial updates internally without pulling fragments of the template out to separate files for rendering, creating a large number of individual templates.
 
+Falco.Markup supports this pattern by way of the `renderFragment` function, which will traverse the provided `XmlNode` tree and render only the child node matching the provided `id`. Otherwise, gracefully returning an empty string if no match is found.
+
+```fsharp
+open Falco.Markup
+
+let view =
+    _div [ _id_ "my-div"; _class_ "my-class" ] [
+        _h1 [ _id_ "my-heading" ] [ _text "hello" ] ]
+
+let render = renderFragment doc "my-heading"
+// produces: <h1 id="my-heading">hello</h1>
+```
 
 ## SVG
 
diff --git a/test/Falco.Markup.Tests/ElemTests.fs b/test/Falco.Markup.Tests/ElemTests.fs
@@ -62,8 +62,7 @@ let ``Should produce valid html doc`` () =
     renderHtml doc |> should equal """<!DOCTYPE html><html><body><div class="my-class"><h1>hello</h1></div></body></html>"""
 
 [<Fact>]
-let ``Should produce valid template fragment from XmlNode and id``()
-    =
+let ``Should produce valid template fragment from XmlNode and id``() =
     let doc =
         _div [ _id_ "my-div"; _class_ "my-class" ] [
             _h1 [ _id_ "my-heading" ] [ _text "hello" ] ]
