Replace front matter with @slide directive for slide configuration

[tilucasoli]

Summary

Propose replacing YAML front matter (--- ... ---) with a @slide directive for configuring slide-level options inline, consistent with how all other SuperDeck annotations work.

Current behavior

Today, slide configuration uses YAML front matter between --- delimiters at the top of each slide:

---
title: Welcome
style: announcement
template: corporate
owner: Platform Team
---

@block
# Hello World

This is parsed by FrontmatterParser which extracts the YAML block, converts it to a Map<String, Object?>, and feeds it into SlideOptions.parse(...).

Known SlideOptions fields

Field	Type	Purpose
title	String?	Slide title (navigation, export)
style	String?	Named style variant from DeckOptions.styles
template	String?	Named template from DeckOptions.templates ('none' to opt out)
args (catch-all)	Map<String, Object?>	Any extra keys, accessible via slide.options.args['key']

How it flows through the system

1. MarkdownParser splits the markdown file into slides (splitting on ---)
2. FrontmatterParser extracts front matter YAML from each slide
3. SlideOptions.parse(frontmatter) validates and creates options
4. SectionParser parses the remaining content into @section/@block/@widget layout
5. CommentParser extracts HTML comments (<!-- ... -->) as speaker notes
6. Everything compiles into a Slide object with key, options, sections, comments

Problem

The --- delimiter serves a dual purpose: it both separates slides and opens/closes front matter. This creates ambiguity:

• A --- in the middle of a slide could be mistaken for a slide separator
• The front matter syntax feels disconnected from the @directive { options } pattern used everywhere else

Proposed solution: @slide directive

Replace front matter with @slide:

@slide {
  title: Welcome
  style: announcement
  template: corporate
  owner: Platform Team
}

@block
# Hello World

Benefits

• Consistent with @section, @block, @widget syntax
• Uses the same YAML options parsing (TagTokenizer already handles @slide { ... })
• Clearer separation of concerns: --- only separates slides, @slide only configures them
• More discoverable for new users (everything is an @ directive)

Slide separation

Slides would still be separated by ---. The @slide directive would be optional (slides without it just have no options).

Backwards compatibility

• YAML front matter could be supported alongside @slide during a transition period
• If both are present, @slide takes precedence (or it's an error)

Acceptance criteria

• @slide { ... } is parsed and populates SlideOptions (title, style, template, args)
• --- continues to work as a slide separator only
• Slides without @slide work normally (no options)
• Legacy front matter still works (deprecation warning)
• TagTokenizer already supports @slide tokenization (no parser changes needed)
• Documentation updated

Related

• packages/builder/lib/src/parsers/front_matter_parser.dart — current front matter extraction
• packages/builder/lib/src/parsers/block_parser.dart — tag-based parsing (would need to handle @slide specially)
• packages/core/lib/src/deck/slide_model.dart — SlideOptions model
• packages/core/lib/src/markdown/tag_tokenizer.dart — already parses @name { yaml } tokens