feat: implement sections and improve comment rendering (#13)

- Add SECTION_HEADER token for parsing section headers (= Section Name, == Name ==)
- Add Section and Comment types to cooklang.go with StepComponent interface
- Update parser to handle section headers and create section components
- Update ToCooklangRecipe to convert section and comment components
- Update HTML renderer: sections as <h3>, comments as styled spans, use fmt.Fprintf
- Update Markdown renderer: sections as ### headings, comments as italicized text
- Add comprehensive tests for section lexing and parsing
- Support various section formats: = Name, == Name, == Name ==, === Name ===
- Sections properly reset step numbering in rendered output

Author: hilli

.gitignore

@@ -23,3 +23,4 @@ go.work.sum
 
 # env file
 .env
+bin

README.md

@@ -59,6 +59,46 @@ Toss everything together and serve.`
 
 See the [Cooklang specification](https://github.com/cooklang/spec/) for details.
 
+### Extended Syntax
+
+This parser supports additional syntax extensions beyond the base Cooklang specification:
+
+#### Ingredient Annotations
+
+Ingredients can have annotations in parentheses to specify preparation notes or state:
+
+```cooklang
+@milk{1%l}(cold)
+```
+
+The annotation `(cold)` is stored as the ingredient's `value` field.
+
+#### Cookware Annotations
+
+Similarly, cookware items can have annotations for usage hints:
+
+```cooklang
+#pan{}(for frying)
+```
+
+#### Named Timers
+
+Timers can have descriptive multi-word names:
+
+```cooklang
+~roast time{4%hours}
+```
+
+#### Comment Preservation
+
+Comments are preserved as a distinct type in the parsed output rather than being discarded:
+
+```cooklang
+-- This is a comment
+```
+
+Comments are accessible with `type: comment` and their text in the `value` field.
+
 ## Developing
 
 ### Prerequisites (Well, not really)

Taskfile.yaml

@@ -24,4 +24,4 @@ tasks:
 
   cli:
     cmds:
-      - go build -o cook ./cmd/cook
+      - go build -o ./bin/cook ./cmd/cook

cooklang.go

@@ -217,6 +217,8 @@ func (Instruction) isStepComponent() {}
 func (Timer) isStepComponent()       {}
 func (Cookware) isStepComponent()    {}
 func (Ingredient) isStepComponent()  {}
+func (Section) isStepComponent()     {}
+func (Comment) isStepComponent()     {}
 
 // Render returns the Cooklang syntax representation of this ingredient.
 // Examples: "@flour{500%g}", "@salt{}", "@milk{2%cups}(cold)"
@@ -319,6 +321,34 @@ func (c Cookware) RenderDisplay() string {
 	return c.Name
 }
 
+// Render returns the Cooklang syntax representation of this section.
+// Examples: "== Section Name =="
+func (s Section) Render() string {
+	if s.Name != "" {
+		return fmt.Sprintf("== %s ==", s.Name)
+	}
+	return "=="
+}
+
+// RenderDisplay returns section name suitable for display.
+func (s Section) RenderDisplay() string {
+	return s.Name
+}
+
+// Render returns the Cooklang syntax representation of this comment.
+// Examples: "-- comment text" for line comments, "[- comment text -]" for block comments
+func (cm Comment) Render() string {
+	if cm.IsBlock {
+		return fmt.Sprintf("[- %s -]", cm.Text)
+	}
+	return fmt.Sprintf("-- %s", cm.Text)
+}
+
+// RenderDisplay returns comment text suitable for display.
+func (cm Comment) RenderDisplay() string {
+	return cm.Text
+}
+
 // Ingredient represents a recipe ingredient with quantity, unit, and optional annotations.
 // Ingredients support unit conversion and consolidation for shopping lists.
 //
@@ -392,6 +422,29 @@ type Cookware struct {
 	CooklangRenderable
 }
 
+// Section represents a section header in a recipe.
+// Sections divide complex recipes into logical parts (e.g., "Dough", "Filling").
+//
+// Example Cooklang syntax: = Dough, == Filling ==
+type Section struct {
+	Name          string        `json:"name,omitempty"`           // Section name (e.g., "Dough", "Filling")
+	NextComponent StepComponent `json:"next_component,omitempty"` // Next component in the step
+	CooklangRenderable
+}
+
+// Comment represents a comment in a recipe.
+// Comments are notes that don't affect the cooking instructions.
+//
+// Example Cooklang syntax:
+// - Line comment: -- This is a comment
+// - Block comment: [- This is a block comment -]
+type Comment struct {
+	Text          string        `json:"text,omitempty"`           // Comment text
+	IsBlock       bool          `json:"is_block,omitempty"`       // True if this is a block comment [- -]
+	NextComponent StepComponent `json:"next_component,omitempty"` // Next component in the step
+	CooklangRenderable
+}
+
 // ParseFile reads and parses a Cooklang recipe file, returning a Recipe object.
 // It automatically detects and includes associated image files matching the recipe filename.
 //
@@ -692,6 +745,20 @@ func ToCooklangRecipe(pRecipe *parser.Recipe) *Recipe {
 				stepComp = &Instruction{
 					Text: component.Value,
 				}
+			case "section":
+				stepComp = &Section{
+					Name: component.Name,
+				}
+			case "comment":
+				stepComp = &Comment{
+					Text:    component.Value,
+					IsBlock: false,
+				}
+			case "blockComment":
+				stepComp = &Comment{
+					Text:    component.Value,
+					IsBlock: true,
+				}
 			}
 
 			if stepComp != nil {
@@ -959,6 +1026,24 @@ func (c *Cookware) GetNext() StepComponent {
 	return c.NextComponent
 }
 
+// SetNext and GetNext methods for Section
+func (s *Section) SetNext(next StepComponent) {
+	s.NextComponent = next
+}
+
+func (s *Section) GetNext() StepComponent {
+	return s.NextComponent
+}
+
+// SetNext and GetNext methods for Comment
+func (cm *Comment) SetNext(next StepComponent) {
+	cm.NextComponent = next
+}
+
+func (cm *Comment) GetNext() StepComponent {
+	return cm.NextComponent
+}
+
 // IngredientList represents a collection of ingredients with unit consolidation capabilities.
 // It provides methods for grouping, converting, and consolidating ingredients for shopping lists
 // and recipe scaling operations.

lexer/lexer.go

@@ -80,7 +80,11 @@ func (l *Lexer) NextToken() token.Token {
 			l.readChar() // consume \n in CRLF sequence
 		}
 		return token.Token{Type: token.NEWLINE, Literal: "\n"}
-	case '=': // = or ==
+	case '=': // Section header
+		// Check if this is at the start of a line (section header)
+		if l.position == 0 || (l.position > 0 && (l.input[l.position-1] == '\n' || l.input[l.position-1] == '\r')) {
+			return l.readSectionHeader()
+		}
 		tok = newToken(token.SECTION, l.ch)
 	case '-':
 		if l.peekChar() == '-' {
@@ -397,3 +401,62 @@ func (l *Lexer) readBlockComment() token.Token {
 		Literal: strings.TrimSpace(commentContent),
 	}
 }
+
+// readSectionHeader reads a section header starting with = and containing an optional name
+// Formats: "= Dough", "== Filling ==", "=== Section Name ==="
+// The number of = symbols doesn't matter, and trailing = symbols are optional
+func (l *Lexer) readSectionHeader() token.Token {
+	// Skip leading = characters
+	for l.ch == '=' {
+		l.readChar()
+	}
+
+	// Skip whitespace after leading =
+	for l.ch == ' ' || l.ch == '\t' {
+		l.readChar()
+	}
+
+	// Read the section name until we hit trailing = or end of line
+	start := l.position
+	for l.ch != '\n' && l.ch != '\r' && l.ch != 0 {
+		// Check if we're hitting trailing = characters
+		if l.ch == '=' {
+			// Check if rest of line is just = and whitespace
+			allEquals := true
+			for i := l.position; i < len(l.input); i++ {
+				ch := l.input[i]
+				if ch == '\n' || ch == '\r' {
+					break
+				}
+				if ch != '=' && ch != ' ' && ch != '\t' {
+					allEquals = false
+					break
+				}
+			}
+			if allEquals {
+				break
+			}
+		}
+		l.readChar()
+	}
+
+	// Extract the section name
+	sectionName := strings.TrimSpace(l.input[start:l.position])
+
+	// Skip trailing = characters
+	for l.ch == '=' {
+		l.readChar()
+	}
+
+	// Skip trailing whitespace
+	for l.ch == ' ' || l.ch == '\t' {
+		l.readChar()
+	}
+
+	// Don't consume the newline - let normal token processing handle it
+
+	return token.Token{
+		Type:    token.SECTION_HEADER,
+		Literal: sectionName,
+	}
+}