Repository navigation
Open
Description
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 WorldThis 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
MarkdownParsersplits the markdown file into slides (splitting on---)FrontmatterParserextracts front matter YAML from each slideSlideOptions.parse(frontmatter)validates and creates optionsSectionParserparses the remaining content into@section/@block/@widgetlayoutCommentParserextracts HTML comments (<!-- ... -->) as speaker notes- Everything compiles into a
Slideobject withkey,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 WorldBenefits
- Consistent with
@section,@block,@widgetsyntax - Uses the same YAML options parsing (
TagTokenizeralready handles@slide { ... }) - Clearer separation of concerns:
---only separates slides,@slideonly 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
@slideduring a transition period - If both are present,
@slidetakes precedence (or it's an error)
Acceptance criteria
-
@slide { ... }is parsed and populatesSlideOptions(title, style, template, args) -
---continues to work as a slide separator only - Slides without
@slidework normally (no options) - Legacy front matter still works (deprecation warning)
-
TagTokenizeralready supports@slidetokenization (no parser changes needed) - Documentation updated
Related
packages/builder/lib/src/parsers/front_matter_parser.dart— current front matter extractionpackages/builder/lib/src/parsers/block_parser.dart— tag-based parsing (would need to handle@slidespecially)packages/core/lib/src/deck/slide_model.dart—SlideOptionsmodelpackages/core/lib/src/markdown/tag_tokenizer.dart— already parses@name { yaml }tokens
Metadata
Metadata
Assignees
Labels
No labels
Activity