Merge pull request #87 from cgreeno/feat/frontmatter

feat: strip YAML frontmatter and render its title above the diagram

Author: AlexanderGrooff

cmd/frontmatter_test.go

@@ -0,0 +1,72 @@
+package cmd
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/AlexanderGrooff/mermaid-ascii/pkg/diagram"
+)
+
+// TestRenderWithFrontmatter checks frontmatter is stripped before type
+// detection for every diagram type, and the title is printed above the output.
+func TestRenderWithFrontmatter(t *testing.T) {
+	cases := []struct {
+		name      string
+		input     string
+		wantType  string
+		wantParts []string
+	}{
+		{
+			"sequence with title",
+			"---\ntitle: Login flow\n---\nsequenceDiagram\nAlice->>Bob: Hi",
+			"sequence",
+			[]string{"Login flow", "Alice", "Bob", "Hi"},
+		},
+		{
+			"er with theme config",
+			"---\nconfig:\n  themeCSS: |\n    rect { fill: red; }\n---\nerDiagram\n  CUSTOMER ||--o{ ORDER : places",
+			"er",
+			[]string{"CUSTOMER", "ORDER", "places"},
+		},
+		{
+			"graph with title",
+			"---\ntitle: Deps\n---\ngraph LR\nA-->B",
+			"graph",
+			[]string{"Deps", "A", "B"},
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			stripped, _ := diagram.StripFrontmatter(c.input)
+			diag, err := DiagramFactory(stripped)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if diag.Type() != c.wantType {
+				t.Errorf("detected %q, want %q", diag.Type(), c.wantType)
+			}
+			out, err := RenderDiagram(c.input, diagram.DefaultConfig())
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, want := range c.wantParts {
+				if !strings.Contains(out, want) {
+					t.Errorf("output missing %q:\n%s", want, out)
+				}
+			}
+		})
+	}
+}
+
+// TestRenderTitleAboveDiagram checks the title sits on the first line,
+// separated from the diagram by a blank line.
+func TestRenderTitleAboveDiagram(t *testing.T) {
+	out, err := RenderDiagram("---\ntitle: My title\n---\ngraph LR\nA-->B", diagram.DefaultConfig())
+	if err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(out, "\n")
+	if lines[0] != "My title" || lines[1] != "" {
+		t.Errorf("want title + blank line first, got %q, %q", lines[0], lines[1])
+	}
+}

cmd/render.go

@@ -11,6 +11,11 @@ func RenderDiagram(input string, config *diagram.Config) (string, error) {
 		config = diagram.DefaultConfig()
 	}
 
+	// YAML frontmatter carries a title and theme config; the config has no
+	// ASCII meaning, but the title is printed above the diagram like mermaid
+	// does. Stripped here once so type detection and parsing never see it.
+	input, title := diagram.StripFrontmatter(input)
+
 	diag, err := DiagramFactory(input)
 	if err != nil {
 		return "", fmt.Errorf("failed to detect diagram type: %w", err)
@@ -25,5 +30,8 @@ func RenderDiagram(input string, config *diagram.Config) (string, error) {
 		return "", fmt.Errorf("failed to render %s diagram: %w", diag.Type(), err)
 	}
 
+	if title != "" {
+		output = title + "\n\n" + output
+	}
 	return output, nil
 }

pkg/diagram/frontmatter.go

@@ -0,0 +1,57 @@
+package diagram
+
+import "strings"
+
+// StripFrontmatter removes a leading YAML frontmatter block (delimited by
+// `---` lines) from a mermaid document, returning the remaining input and the
+// frontmatter's title, if one was set.
+//
+// Mermaid uses frontmatter for a diagram title and theme/config overrides
+// (colors, CSS). The config has no meaning in ASCII output, so it is
+// discarded; the title is surfaced so callers can print it above the diagram,
+// as mermaid does.
+//
+// Matching mermaid's own frontmatter semantics (frontmatter.spec.ts):
+// frontmatter is only recognised at the start of the document, the closing
+// delimiter must sit at the same indentation as the opening one, and an
+// unclosed block is not frontmatter at all — the input is returned untouched
+// for the diagram parser to deal with.
+func StripFrontmatter(input string) (rest string, title string) {
+	lines := strings.Split(input, "\n")
+
+	start := 0
+	for start < len(lines) && strings.TrimSpace(lines[start]) == "" {
+		start++
+	}
+	if start >= len(lines) || !isDelimiter(lines[start]) {
+		return input, ""
+	}
+	indent := lines[start][:strings.Index(lines[start], "-")]
+
+	for i := start + 1; i < len(lines); i++ {
+		if isDelimiter(lines[i]) && lines[i][:strings.Index(lines[i], "-")] == indent {
+			return strings.Join(lines[i+1:], "\n"), title
+		}
+		// Only a top-level `title:` key counts — indented occurrences are
+		// nested config values (e.g. inside themeCSS), not the title. YAML
+		// requires whitespace after the colon for a mapping ("title:xyz" is a
+		// plain scalar, not a key), and an unquoted value ends at a comment.
+		trimmed := strings.TrimRight(lines[i], " \t\r")
+		if v, ok := strings.CutPrefix(trimmed, indent+"title:"); ok && (v == "" || v[0] == ' ' || v[0] == '\t') {
+			v = strings.TrimSpace(v)
+			if !strings.HasPrefix(v, `"`) && !strings.HasPrefix(v, `'`) {
+				if idx := strings.Index(v, " #"); idx != -1 {
+					v = strings.TrimSpace(v[:idx])
+				}
+			}
+			title = strings.Trim(v, `"'`)
+		}
+	}
+	return input, ""
+}
+
+// isDelimiter reports whether a line is a frontmatter delimiter: `---` with
+// optional surrounding whitespace.
+func isDelimiter(line string) bool {
+	return strings.TrimSpace(line) == "---"
+}

pkg/diagram/frontmatter_test.go

@@ -0,0 +1,43 @@
+package diagram
+
+import "testing"
+
+// Cases mirror mermaid's own frontmatter.spec.ts semantics.
+func TestStripFrontmatter(t *testing.T) {
+	cases := []struct {
+		name      string
+		in        string
+		wantRest  string
+		wantTitle string
+	}{
+		{"no frontmatter", "graph TD\nA-->B", "graph TD\nA-->B", ""},
+		{"title extracted", "---\ntitle: foo\n---\ndiagram", "diagram", "foo"},
+		{"empty frontmatter", "---\n\n---\ndiagram", "diagram", ""},
+		{"unclosed is not frontmatter", "---\ntitle: foo\ndiagram", "---\ntitle: foo\ndiagram", ""},
+		{"only at document start", "diagram\n---\ntitle: foo\n---", "diagram\n---\ntitle: foo\n---", ""},
+		{"delimiter inside a value line", "---\ntitle: foo---bar\n---\ndiagram", "diagram", "foo---bar"},
+		{"unknown keys ignored", "---\nconfig:\n  theme: dark\ninvalid: x\n---\ndiagram", "diagram", ""},
+		{"quoted title", "---\ntitle: \"Customers service\"\n---\ndiagram", "diagram", "Customers service"},
+		{"boolean-looking title stays text", "---\ntitle: true\n---\ndiagram", "diagram", "true"},
+		{"leading blank lines", "\n\n---\ntitle: t\n---\ndiagram", "diagram", "t"},
+		{"matching indented delimiters", "  ---\n  title: t\n  ---\ndiagram", "diagram", "t"},
+		{"mismatched closing indent not a close", "---\ntitle: t\n   ---\ndiagram", "---\ntitle: t\n   ---\ndiagram", ""},
+		{"indented title is not the title", "---\nconfig:\n  title: nested\n---\ndiagram", "diagram", ""},
+		{"crlf input", "---\r\ntitle: t\r\n---\r\ndiagram", "diagram", "t"},
+		{"multiline themeCSS config", "---\nconfig:\n  themeCSS: |\n    rect { fill: red; }\n---\nerDiagram", "erDiagram", ""},
+		{"inline comment stripped from title", "---\ntitle: hi # note\n---\ndiagram", "diagram", "hi"},
+		{"hash kept inside quoted title", "---\ntitle: \"a # b\"\n---\ndiagram", "diagram", "a # b"},
+		{"no space after colon is not a mapping", "---\ntitle:xyz\n---\ndiagram", "diagram", ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			rest, title := StripFrontmatter(c.in)
+			if rest != c.wantRest {
+				t.Errorf("rest = %q, want %q", rest, c.wantRest)
+			}
+			if title != c.wantTitle {
+				t.Errorf("title = %q, want %q", title, c.wantTitle)
+			}
+		})
+	}
+}