Fix figcaption parsing error and refactor figure processing to use native hype parser patterns (#44)

* fix caption parsing

* more fixes

* Update README.md with latest Hype changes

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: corylanou

README.md

@@ -127,7 +127,7 @@ $ go run .
 Hello World
 
 --------------------------------------------------------------------------------
-Go Version: go1.24.2
+Go Version: go1.24.4
 
 ```
 
@@ -160,7 +160,7 @@ $ go run .
 Hello World
 
 --------------------------------------------------------------------------------
-Go Version: go1.24.2
+Go Version: go1.24.4
 
 ```
 
@@ -189,7 +189,7 @@ $ go run .
 Hello World
 
 --------------------------------------------------------------------------------
-Go Version: go1.24.2
+Go Version: go1.24.4
 
 ```
 
@@ -219,7 +219,7 @@ $ go run .
 ./main.go:7:6: undefined: fmt.Prin
 
 --------------------------------------------------------------------------------
-Go Version: go1.24.2
+Go Version: go1.24.4
 
 ```
 
@@ -256,7 +256,7 @@ type Context interface{ ... }
     func WithoutCancel(parent Context) Context
 
 --------------------------------------------------------------------------------
-Go Version: go1.24.2
+Go Version: go1.24.4
 
 ```
 
@@ -279,7 +279,7 @@ func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
     call cancel as soon as the operations running in this Context complete.
 
 --------------------------------------------------------------------------------
-Go Version: go1.24.2
+Go Version: go1.24.4
 
 ```
 

figcaption_test.go

@@ -1,6 +1,10 @@
 package hype
 
-import "testing"
+import (
+	"context"
+	"strings"
+	"testing"
+)
 
 func Test_Figcaption_MarshalJSON(t *testing.T) {
 	t.Parallel()
@@ -11,5 +15,45 @@ func Test_Figcaption_MarshalJSON(t *testing.T) {
 	fig.Nodes = append(fig.Nodes, Text("This is a caption"))
 
 	testJSON(t, "figcaption", fig)
+}
+
+// Test that verifies the fix for figcaption elements being lost when mixed with <go> elements
+func Test_Figcaption_With_Go_Elements(t *testing.T) {
+	t.Parallel()
+
+	// This structure was previously failing with "execute error: no figcaption"
+	input := `<figure id="ticker" type="listing">
+<go doc="time.Ticker"></go>
+<figcaption>The <godoc>time#Ticker</godoc> function.</figcaption>
+</figure>`
+
+	p := testParser(t, "")
+
+	doc, err := p.Parse(strings.NewReader(input))
+	if err != nil {
+		t.Fatalf("unexpected error during parsing: %v", err)
+	}
 
+	// Execute the document - this should now work without the "no figcaption" error
+	ctx := context.Background()
+	err = doc.Execute(ctx)
+	if err != nil {
+		t.Fatalf("unexpected error during execution: %v", err)
+	}
+
+	// Verify that the figcaption is properly parsed and available
+	figures := ByType[*Figure](doc.Nodes)
+	if len(figures) == 0 {
+		t.Fatal("no figures found")
+	}
+
+	fig := figures[0]
+	figcaptions := ByType[*Figcaption](fig.Nodes)
+	if len(figcaptions) == 0 {
+		t.Fatal("no figcaption found in figure - the fix didn't work")
+	}
+
+	if len(figcaptions) != 1 {
+		t.Fatalf("expected 1 figcaption, got %d", len(figcaptions))
+	}
 }

figure.go

@@ -2,11 +2,11 @@ package hype
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"strings"
 
 	"github.com/gobuffalo/flect"
+	"golang.org/x/net/html"
 )
 
 type Figure struct {
@@ -108,37 +108,85 @@ func NewFigure(p *Parser, el *Element) (*Figure, error) {
 		f.style = style
 	}
 
+	// Check if we need to process any markdown content (like ``` code blocks)
+	// If the figure content contains raw markdown that wasn't preprocessed,
+	// we need to process it while preserving all elements
 	body := f.Nodes.String()
-	body = strings.TrimSpace(body)
+	if strings.Contains(body, "```") {
+		// Process the content through markdown preprocessing but preserve
+		// the structure by re-parsing the result
+		nodes, err := f.processMarkdownContent(p, body)
+		if err != nil {
+			return nil, f.WrapErr(err)
+		}
+		f.Nodes = nodes
+	}
 
-	if len(body) == 0 {
-		return f, nil
+	return f, nil
+}
+
+// processMarkdownContent processes figure content that contains markdown syntax
+// while preserving all elements including figcaption
+func (f *Figure) processMarkdownContent(p *Parser, body string) (Nodes, error) {
+	// Create a sub-parser with pages disabled to avoid wrapping figure content in <page> tags
+	subParser, err := p.Sub(".")
+	if err != nil {
+		return nil, err
 	}
+	subParser.DisablePages = true
 
-	p2, err := p.Sub(".")
+	// Run the content through the preprocessing pipeline to handle markdown syntax
+	r := strings.NewReader(body)
+
+	// Apply preprocessing (including markdown conversion) with pages disabled
+	processedReader, err := subParser.PreParsers.PreParse(subParser, r)
 	if err != nil {
-		return nil, f.WrapErr(err)
+		return nil, err
 	}
 
-	nodes, err := p2.ParseFragment(strings.NewReader(body))
+	// Parse the preprocessed content as HTML
+	htmlDoc, err := html.Parse(processedReader)
 	if err != nil {
-		if !errors.Is(err, ErrNilFigure) {
-			return nil, f.WrapErr(err)
-		}
+		return nil, err
 	}
 
-	pages := ByType[*Page](nodes)
-	if len(pages) == 0 {
-		f.Nodes = nodes
+	// Extract the body content (preprocessing wraps content in <html><head></head><body>)
+	var bodyElement *html.Node
+	var findBody func(*html.Node)
+	findBody = func(node *html.Node) {
+		if node.Type == html.ElementNode && node.Data == "body" {
+			bodyElement = node
+			return
+		}
+		for child := node.FirstChild; child != nil; child = child.NextSibling {
+			findBody(child)
+			if bodyElement != nil {
+				return
+			}
+		}
+	}
+	findBody(htmlDoc)
 
-		return f, nil
+	if bodyElement == nil {
+		return nil, fmt.Errorf("could not find body element after preprocessing")
 	}
 
-	page := pages[0]
+	// Parse each child of the body as a hype node
+	var nodes Nodes
+	for child := bodyElement.FirstChild; child != nil; child = child.NextSibling {
+		// Skip pure whitespace text nodes for cleaner output
+		if child.Type == html.TextNode && strings.TrimSpace(child.Data) == "" {
+			continue
+		}
 
-	f.Nodes = page.Nodes
+		node, err := subParser.ParseHTMLNode(child, f)
+		if err != nil {
+			return nil, err
+		}
+		nodes = append(nodes, node)
+	}
 
-	return f, nil
+	return nodes, nil
 }
 
 func NewFigureNodes(p *Parser, el *Element) (Nodes, error) {

testdata/auto/refs/fenced/hype.gold

@@ -5,8 +5,7 @@
 
 <p>In C#, <ref id="figure-1-1"><a href="#figure-1-1">Figure 1.1</a></ref>, you declare that you are using the <code>Performer</code> interface by using the <code>:</code> operator after the class name and listing the interfaces you want to use.</p>
 
-<figure id="figure-1-1">
-<pre><code class="language-c#" language="c#">interface Performer {
+<figure id="figure-1-1"><pre><code class="language-c#" language="c#">interface Performer {
 	void Perform();
 }
 
@@ -15,28 +14,21 @@ class Musician : Performer {
 	public void Perform() {}
 }
 
-</code></pre>
-
-<figcaption><em class="figure-name">Figure 1.1:</em> Example C# implementation of the <code>Performer</code> interface.</figcaption>
-</figure>
+</code></pre><figcaption><em class="figure-name">Figure 1.1:</em> Example C# implementation of the <code>Performer</code> interface.</figcaption></figure>
 
 <p>In Java, <ref id="figure-1-2"><a href="#figure-1-2">Figure 1.2</a></ref>, you use the <code>implements</code> keyword after the class name to tell the compiler that your type wants to implement the <code>Performer</code> interface.</p>
 
 <div>
 
-<figure id="figure-1-2">
-<pre><code class="language-java" language="java">interface Performer {
+<figure id="figure-1-2"><pre><code class="language-java" language="java">interface Performer {
 	void Perform();
 }
 
 // explicitly implements Performer
 class Musician implements Performer {
 	void Perform() {}
 }
-</code></pre>
-
-<figcaption><em class="figure-name">Figure 1.2:</em> Example Java implementation of <code>Performer</code> interface.</figcaption>
-</figure>
+</code></pre><figcaption><em class="figure-name">Figure 1.2:</em> Example Java implementation of <code>Performer</code> interface.</figcaption></figure>
 
 </div>
 </page>

testdata/auto/refs/images/hype.gold

@@ -2,6 +2,7 @@
 <h1>Image in a figure</h1>
 
 <figure id="figure-1-1">
+
 <img alt="1" src="assets/nodes.svg"></img>
 
 <img alt="2" src="assets/nodes.svg"></img>
@@ -11,6 +12,7 @@
 Hello</code></pre></cmd>
 
 <figcaption><em class="figure-name">Figure 1.1:</em> Image caption</figcaption>
+
 </figure>
 </page>
 </body></html>

testdata/auto/refs/includes/hype.gold

@@ -4,11 +4,13 @@
 <p>In <ref id="figure-1-1"><a href="#figure-1-1">Figure 1.1</a></ref> we see the reference.</p>
 
 <figure id="figure-1-1">
+
 <pre><code class="language-go" language="go" src="src/greet/main.go#example">fmt.Println("Hello, World!")</code></pre>
 
 <img src="assets/foo.png"></img>
 
 <figcaption><em class="figure-name">Figure 1.1:</em> Optional caption</figcaption>
+
 </figure>
 </page>
 <page>

testdata/auto/refs/simple/hype.gold

@@ -4,11 +4,13 @@
 <p>In <ref id="figure-1-1"><a href="#figure-1-1">Figure 1.1</a></ref> we see the reference.</p>
 
 <figure id="figure-1-1">
+
 <pre><code class="language-go" language="go" src="src/greet/main.go#example">fmt.Println("Hello, World!")</code></pre>
 
 <img src="assets/foo.png"></img>
 
 <figcaption><em class="figure-name">Figure 1.1:</em> Optional caption</figcaption>
+
 </figure>
 
 <p>Some more text that references <ref id="figure-1-1"><a href="#figure-1-1">Figure 1.1</a></ref>.</p>