feature(renderer): Example blocks should support custom captions

This introduces custom captions to example blocks, and it works
just like asciidoctor, including the global example-caption
and counter:example-number attributes.

pkg/renderer/sgml/delimited_block.go

@@ -306,18 +306,34 @@ func (r *sgmlRenderer) renderExampleBlock(ctx *renderer.Context, b types.Delimit
 		return r.renderAdmonitionBlock(ctx, b)
 	}
 	result := &strings.Builder{}
+	caption := &strings.Builder{}
 
 	// default, example block
-	number := ctx.GetAndIncrementExampleBlockCounter()
+	number := 0
 	elements := b.Elements
 	content, err := r.renderElements(ctx, elements)
 	if err != nil {
 		return "", errors.Wrap(err, "unable to render example block content")
 	}
+
+	c, ok := b.Attributes.GetAsString(types.AttrCaption)
+	if !ok {
+		c, _ = ctx.Attributes.GetAsString(types.AttrExampleCaption)
+		if c != "" {
+			c += " {counter:example-number}. "
+		}
+	}
+	// TODO: Replace this hack when we have attribute substitution fully working
+	if strings.Contains(c, "{counter:example-number}") {
+		number = ctx.GetAndIncrementExampleBlockCounter()
+		c = strings.ReplaceAll(c, "{counter:example-number}", strconv.Itoa(number))
+	}
+	caption.WriteString(c)
 	err = r.exampleBlock.Execute(result, struct {
 		Context       *renderer.Context
 		ID            sanitized
 		Title         sanitized
+		Caption       string
 		Roles         sanitized
 		ExampleNumber int
 		Content       sanitized
@@ -326,6 +342,7 @@ func (r *sgmlRenderer) renderExampleBlock(ctx *renderer.Context, b types.Delimit
 		Context:       ctx,
 		ID:            r.renderElementID(b.Attributes),
 		Title:         r.renderElementTitle(b.Attributes),
+		Caption:       caption.String(),
 		Roles:         r.renderElementRoles(b.Attributes),
 		ExampleNumber: number,
 		Content:       sanitized(content),

pkg/renderer/sgml/html5/delimited_block.go

@@ -32,7 +32,7 @@ const (
 
 	exampleBlockTmpl = `<div {{ if .ID }}id="{{ .ID }}" {{ end }}` +
 		"class=\"exampleblock{{ if .Roles }} {{ .Roles }}{{ end }}\">\n" +
-		"{{ if .Title }}<div class=\"title\">Example {{ .ExampleNumber }}. {{ .Title }}</div>\n{{ end }}" +
+		"{{ if .Title }}<div class=\"title\">{{ .Caption }}{{ .Title }}</div>\n{{ end }}" +
 		"<div class=\"content\">\n" +
 		"{{ .Content }}" +
 		"</div>\n" +

pkg/renderer/sgml/html5/delimited_block_test.go

@@ -546,6 +546,64 @@ foo
 `
 			Expect(RenderHTML(source)).To(MatchHTML(expected))
 		})
+
+		It("example block with custom caption and title", func() {
+			source := `[caption="Caption A. "]
+.example block title
+====
+foo
+
+====`
+			expected := `<div class="exampleblock">
+<div class="title">Caption A. example block title</div>
+<div class="content">
+<div class="paragraph">
+<p>foo</p>
+</div>
+</div>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+		It("example block with custom global caption and title", func() {
+			source := `:example-caption: Caption
+
+.example block title
+====
+foo
+
+====`
+			expected := `<div class="exampleblock">
+<div class="title">Caption 1. example block title</div>
+<div class="content">
+<div class="paragraph">
+<p>foo</p>
+</div>
+</div>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+		It("example block with suppressed caption and title", func() {
+			source := `:example-caption!:
+
+.example block title
+====
+foo
+
+====`
+			expected := `<div class="exampleblock">
+<div class="title">example block title</div>
+<div class="content">
+<div class="paragraph">
+<p>foo</p>
+</div>
+</div>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+
 	})
 
 	Context("admonition blocks", func() {

pkg/renderer/sgml/xhtml5/delimited_block_test.go

@@ -546,6 +546,64 @@ foo
 `
 			Expect(RenderXHTML(source)).To(MatchHTML(expected))
 		})
+
+		It("example block with custom caption and title", func() {
+			source := `[caption="Caption A. "]
+.example block title
+====
+foo
+
+====`
+			expected := `<div class="exampleblock">
+<div class="title">Caption A. example block title</div>
+<div class="content">
+<div class="paragraph">
+<p>foo</p>
+</div>
+</div>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+		It("example block with custom global caption and title", func() {
+			source := `:example-caption: Caption
+
+.example block title
+====
+foo
+
+====`
+			expected := `<div class="exampleblock">
+<div class="title">Caption 1. example block title</div>
+<div class="content">
+<div class="paragraph">
+<p>foo</p>
+</div>
+</div>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+		It("example block with suppressed caption and title", func() {
+			source := `:example-caption!:
+
+.example block title
+====
+foo
+
+====`
+			expected := `<div class="exampleblock">
+<div class="title">example block title</div>
+<div class="content">
+<div class="paragraph">
+<p>foo</p>
+</div>
+</div>
+</div>
+`
+			Expect(RenderHTML(source)).To(MatchHTML(expected))
+		})
+
 	})
 
 	Context("admonition blocks", func() {

pkg/types/attributes.go

@@ -111,6 +111,8 @@ const (
 	AttrPositional3 = "@3"
 	// AttrVersionLabel labels the version number in the document
 	AttrVersionLabel = "version-label"
+	// AttrExampleCaption is the example caption
+	AttrExampleCaption = "example-caption"
 	// AttrFigureCaption is the figure (image) caption
 	AttrFigureCaption = "figure-caption"
 	// AttrTableCaption is the table caption

pkg/types/predefined_attributes.go

@@ -35,6 +35,7 @@ func init() {
 		"two-semicolons":     ";",
 		"cpp":                "C++",
 		AttrVersionLabel:     "version",
+		AttrExampleCaption:   "Example",
 		AttrTableCaption:     "Table",
 		AttrFigureCaption:    "Figure",
 		AttrCautionCaption:   "Caution",