Add Markdown YAML front matter

Author: rupor-github

convert/textout/render.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"slices"
+	"strconv"
 	"strings"
 	"unicode"
 	"unicode/utf8"
@@ -136,12 +137,14 @@ func (r *renderer) render() ([]byte, error) {
 }
 
 func (r *renderer) renderFrontMatter() {
-	info := r.c.Book.Description.TitleInfo
-	title := strings.TrimSpace(info.BookTitle.Value)
-	if title == "" {
-		title = strings.TrimSuffix(r.c.SrcName, ".fb2")
+	if r.format == formatMD {
+		r.renderMarkdownFrontMatter()
+		r.heading(r.plainInline(r.bookTitle()), 1)
+		return
 	}
-	r.heading(r.plainInline(title), 1)
+
+	info := r.c.Book.Description.TitleInfo
+	r.heading(r.plainInline(r.bookTitle()), 1)
 
 	lines := make([]string, 0, 6)
 	if authors := formatAuthors(info.Authors); authors != "" {
@@ -162,6 +165,111 @@ func (r *renderer) renderFrontMatter() {
 	r.paragraph(strings.Join(lines, "\n"))
 }
 
+func (r *renderer) bookTitle() string {
+	title := strings.TrimSpace(r.c.Book.Description.TitleInfo.BookTitle.Value)
+	if title == "" {
+		return strings.TrimSuffix(r.c.SrcName, ".fb2")
+	}
+	return title
+}
+
+func (r *renderer) renderMarkdownFrontMatter() {
+	info := r.c.Book.Description.TitleInfo
+	lines := []string{"---"}
+	if title := r.markdownMetaTitle(); title != "" {
+		lines = append(lines, "title: "+yamlScalar(title))
+	}
+	if authors := r.markdownMetaAuthors(info.Authors); len(authors) > 0 {
+		lines = append(lines, "authors:")
+		for _, author := range authors {
+			lines = append(lines, "  - "+yamlScalar(author))
+		}
+	}
+	if len(info.Sequences) > 0 {
+		lines = append(lines, "series:")
+		for _, seq := range info.Sequences {
+			name := strings.TrimSpace(seq.Name)
+			if name == "" {
+				continue
+			}
+			lines = append(lines, "  - name: "+yamlScalar(name))
+			if seq.Number != nil {
+				lines = append(lines, "    number: "+strconv.Itoa(*seq.Number))
+			}
+		}
+	}
+	if lang := strings.TrimSpace(info.Lang.String()); lang != "" && lang != "und" {
+		lines = append(lines, "language: "+yamlScalar(lang))
+	}
+	if date := formatDate(info.Date); date != "" {
+		lines = append(lines, "date: "+yamlScalar(date))
+	}
+	if genres := markdownMetaGenres(info.Genres); len(genres) > 0 {
+		lines = append(lines, "genres:")
+		for _, genre := range genres {
+			lines = append(lines, "  - "+yamlScalar(genre))
+		}
+	}
+	lines = append(lines, "---")
+	r.block(strings.Join(lines, "\n"))
+}
+
+func (r *renderer) markdownMetaTitle() string {
+	templateText := strings.TrimSpace(r.cfg.Metainformation.TitleTemplate)
+	if templateText != "" {
+		title, err := r.c.Book.ExpandTemplateMetainfo(config.MetaTitleTemplateFieldName, templateText, r.c.SrcName, r.c.OutputFormat)
+		if err == nil && strings.TrimSpace(title) != "" {
+			return strings.TrimSpace(title)
+		}
+	}
+	title := strings.TrimSpace(r.c.Book.Description.TitleInfo.BookTitle.Value)
+	if title == "" {
+		return strings.TrimSuffix(r.c.SrcName, ".fb2")
+	}
+	return title
+}
+
+func (r *renderer) markdownMetaAuthors(authors []fb2.Author) []string {
+	result := make([]string, 0, len(authors))
+	templateText := strings.TrimSpace(r.cfg.Metainformation.CreatorNameTemplate)
+	for i := range authors {
+		name := ""
+		if templateText != "" {
+			expanded, err := r.c.Book.ExpandTemplateAuthorName(
+				config.MetaCreatorNameTemplateFieldName,
+				templateText,
+				r.c.OutputFormat,
+				i,
+				&authors[i],
+			)
+			if err == nil {
+				name = strings.TrimSpace(expanded)
+			}
+		}
+		if name == "" {
+			name = formatAuthor(authors[i])
+		}
+		if name != "" {
+			result = append(result, name)
+		}
+	}
+	return result
+}
+
+func markdownMetaGenres(genres []fb2.GenreRef) []string {
+	result := make([]string, 0, len(genres))
+	for _, genre := range genres {
+		if text := strings.TrimSpace(genre.Value); text != "" {
+			result = append(result, text)
+		}
+	}
+	return result
+}
+
+func yamlScalar(text string) string {
+	return strconv.Quote(text)
+}
+
 func (r *renderer) renderAnnotation() {
 	r.heading(r.plainInline(annotationTitle(r.cfg)), 2)
 	r.renderFlow(r.c.Book.Description.TitleInfo.Annotation.Items, 0, blockNormal)

convert/textout/render_test.go

@@ -55,9 +55,9 @@ func TestRenderMarkdownSemanticOutput(t *testing.T) {
 		t.Fatalf("Render() error = %v", err)
 	}
 
-	assertContains(t, got, "# Test Book")
-	assertContains(t, got, "Authors: Ada Lovelace")
-	assertContains(t, got, "Series: Series #1")
+	assertContains(t, got, "---\ntitle: \"Test Book\"\nauthors:\n  - \"Ada Lovelace\"\nseries:\n  - name: \"Series\"\n    number: 1")
+	assertContains(t, got, "language: \"en\"")
+	assertContains(t, got, "genres:\n  - \"sf\"\n---\n\n# Test Book")
 	assertContains(t, got, "## Chapter \\*One\\*")
 	assertContains(t, got, "Hello **world** [site](https://example.com)")
 	assertContains(t, got, "See [Chapter](#chapter-1) end")
@@ -67,6 +67,36 @@ func TestRenderMarkdownSemanticOutput(t *testing.T) {
 	assertContains(t, got, "| --- | --- |")
 }
 
+func TestRenderMarkdownFrontMatterUsesMetainformationTemplates(t *testing.T) {
+	c := testContent(common.OutputFmtMd)
+	noteNum := 2
+	c.Book.Description.TitleInfo.Authors = []fb2.Author{{FirstName: "Ada", LastName: "Lovelace"}}
+	c.Book.Description.TitleInfo.Sequences = []fb2.Sequence{{Name: "Analytical Engine", Number: &noteNum}}
+	c.Book.Bodies = []fb2.Body{{
+		Kind: fb2.BodyMain,
+		Sections: []fb2.Section{{
+			ID:      "chapter-1",
+			Title:   title("Chapter"),
+			Content: []fb2.FlowItem{paragraphItem(fb2.InlineSegment{Kind: fb2.InlineText, Text: "Text"})},
+		}},
+	}}
+	cfg := testConfig()
+	cfg.Metainformation.TitleTemplate = `{{ with first .Series }}{{ .Name }} #{{ .Number }}: {{ end }}{{ .Title }}`
+	cfg.Metainformation.CreatorNameTemplate = `{{ .LastName }}, {{ .FirstName }}`
+
+	got, err := renderForTest(c, cfg)
+	if err != nil {
+		t.Fatalf("Render() error = %v", err)
+	}
+
+	assertContains(t, got, "title: \"Analytical Engine #2: Test Book\"")
+	assertContains(t, got, "authors:\n  - \"Lovelace, Ada\"")
+	assertContains(t, got, "---\n\n# Test Book")
+	if strings.Contains(got, "# Analytical Engine #2: Test Book") || strings.Contains(got, "Authors: Ada Lovelace") {
+		t.Fatalf("Markdown rendered legacy metadata block instead of YAML front matter:\n%s", got)
+	}
+}
+
 func TestRenderMarkdownTOCLinksToStableAnchors(t *testing.T) {
 	c := testContent(common.OutputFmtMd)
 	c.Book.Bodies = []fb2.Body{{

docs/formats/text.md

@@ -17,6 +17,8 @@ TXT output:
 Markdown output:
 
 - Produces UTF-8 semantic Markdown with headings, paragraphs, links, tables, block quotes, fenced code blocks, and optional image output.
+- Starts with YAML front matter containing title, authors, series, language, date, and genres when available.
+- Uses `document.metainformation.title_template` and `creator_name_template` for YAML front matter title and author values.
 - Emits explicit anchors for section and note targets.
 - Uses Markdown pipe tables, including inside collected endnotes.
 - Preserves code listings as fenced code blocks when a paragraph is entirely code.