Specialized Layouts

ZiraDocs provides specialized slide layouts. Setting one types the slide, picks the content schema the linter validates it against, and puts the type in the generated HTML. Nine of them also ship their own CSS; the rest render like a content slide. Which is which is in Slide Layouts, and this page says per layout what its styling actually does.

Overview

Specialized layouts help you create professional presentations by:

Styling for the covered layouts - a CSS file per layout, loaded only when a slide uses it
Content validation - Built-in rules ensure appropriate content for each layout type
Written against real content - each stylesheet targets the shape those slides actually have in the example decks, not an imagined one
Cross-mode support - Available in both Strict Mode and Flex Mode

Layout Types

Basic Layouts

`title` - Title Slide Layout

Purpose: Primary presentation cover slide

Styling:

Typed and validated like any other layout. The base stylesheet already dresses this slide type, so it has no separate layout CSS

Strict Mode:

SLIDE title
  heading: "My Presentation"
  subtitle: "Descriptive subtitle"
  logo: "assets/logo.png"

Flex Mode:

---
layout: title
---

# My Presentation
## Descriptive subtitle

![Logo](assets/logo.png)

Validation Rules:

Must have heading or title — LAYOUT001 is an error, and it fires only when both are missing. Prefer heading: it is the property the schema lists as required and the one the renderer reaches for first.
Should avoid complex content elements
Maximum 1 decorative element allowed

`content` - General Content Layout

Purpose: Standard content slides for main presentation material

Styling:

Typed and validated like any other layout. The base stylesheet already dresses this slide type, so it has no separate layout CSS

Strict Mode:

SLIDE content
  title: "Main Content"
  TEXT
    Regular content with mixed elements.
  POINTS
    - First point
    - Second point

Flex Mode:

---
layout: content
---

# Main Content

Regular content with mixed elements.

- First point
- Second point

Validation Rules:

Must have a title
Must have at least one content element
No restrictions on element types

`section` - Section Introduction Layout

Purpose: Introduction slides for new presentation sections

Styling:

Typed and validated like any other layout. The base stylesheet already dresses this slide type, so it has no separate layout CSS

Strict Mode:

SLIDE section
  title: "Development Methodology"
  subtitle: "Processes and best practices"
  TEXT
    In this section we'll explore agile methodologies
    and how to implement them in our projects.

Flex Mode:

---
layout: section
---

# Development Methodology
## Processes and best practices

In this section we'll explore agile methodologies
and how to implement them in our projects.

Validation Rules:

Must have title or subtitle
Should contain simple, introductory content
Avoids complex elements (code, charts, tables)

Comparison and Analysis Layouts

`comparison` - Side-by-Side Comparison Layout

Purpose: Compare two or more options side by side

What the styling does:

The slide’s elements become a grid that fits as many columns as the width allows, so two or three ::: blocks read side by side instead of stacked
Anything that is not a ::: block — an intro paragraph, a table — spans the full width instead of becoming another column
Accepts the columns option (1-4) to fix the number of columns

Strict Mode:

SLIDE comparison
  title: "Framework Comparison"
  :::info
    title: "React"
    content: "Component-based, virtual DOM, large ecosystem"
  :::success
    title: "Vue"
    content: "Progressive, template-based, gentle learning curve"

Flex Mode:

---
layout: comparison
---

# Framework Comparison

:::info React
Component-based, virtual DOM, large ecosystem
:::

:::success Vue
Progressive, template-based, gentle learning curve
:::

Validation Rules:

Must have balanced content sections
Minimum 2 comparable elements
Supports tables, points, and special blocks

`stats` - Statistics and Data Layout

Purpose: Display statistical information and data visualizations

What the styling does:

The table takes the full width, its header uses the primary colour, and its digits are set in tabular figures so the numbers line up in a column
The first column of the table is set semibold, which is where the metric names usually go
Accepts the columns option (1-4): with it, the ::: blocks after the table read as a strip of indicators and the table still spans the full width

Strict Mode:

SLIDE stats
  title: "Performance Metrics"
  TABLE
    headers: ["Metric", "Q3", "Q4", "Growth"]
    rows: [
      ["Revenue", "$1.2M", "$1.8M", "+50%"],
      ["Users", "15K", "23K", "+53%"]
    ]

Flex Mode:

---
layout: stats
---

# Performance Metrics

| Metric | Q3 | Q4 | Growth |
|--------|----|----|--------|
| Revenue | $1.2M | $1.8M | +50% |
| Users | 15K | 23K | +53% |

Validation Rules:

Must include data elements (charts, tables, or metrics)
Minimum 1 data visualization element
Avoids code blocks and diagrams

Technical and Content Layouts

`code_example` - Code Example Layout

Purpose: Technical documentation and code demonstrations

What the styling does:

The code is set slightly larger and capped in height (max-height: 55vh), so a long listing scrolls instead of pushing the rest of the slide off screen
Bullets around the code are set slightly smaller, so the explanation does not compete with it

Strict Mode:

SLIDE code_example
  title: "API Implementation"
  TEXT
    Basic usage example:
  CODE javascript
    const api = new DataProcessor({
      endpoint: 'https://api.example.com',
      apiKey: process.env.API_KEY
    });

    const result = await api.process(inputData);

Flex Mode:

---
layout: code_example
---

# API Implementation

Basic usage example:

```javascript
const api = new DataProcessor({
  endpoint: 'https://api.example.com',
  apiKey: process.env.API_KEY
});

const result = await api.process(inputData);

**Validation Rules:**
- Must contain at least one code block
- Should include explanatory text
- Optimized for technical content

### Marketing and Communication Layouts

#### `hero` - Hero/Impact Visual Layout

**Purpose:** Maximum visual impact with hero elements

**What the styling does:**
- The content is centred on both axes and the `h1` grows, without the underline the base gives a content slide's heading
- The whole slide takes the title slide's background token, so an external theme changes it without touching this file
- Images are capped in height so they do not crowd the statement
- Accepts the `align` option (`left` or `center`)

**Strict Mode:**
```slidelang
SLIDE hero
  title: "Revolutionizing the Future"
  subtitle: "The next generation is here"
  align: center
  IMAGE "images/hero-bg.jpg"
    alt: "The product in use"
  TEXT
    [Discover More](https://example.com/start)

Flex Mode:

---
layout: hero
background: "images/hero-bg.jpg"
---

# Revolutionizing the Future
## The next generation is here

[Discover More](#cta){.btn-primary}

Validation Rules:

Must have a title
Maximum 3 content elements
Avoids complex elements (code, tables, charts)

`testimonial` - Testimonial Layout

Purpose: Display customer testimonials and social proof

What the styling does:

The blockquote is set large and italic; the cite under it is styled as an attribution
The content is centred
The opening quotation mark comes from the shared quote styling, not from this layout
Accepts the align option (left or center)

Strict Mode:

SLIDE testimonial
  title: "What our customers say"
  QUOTE
    This solution increased our productivity by 300% in just three months.
    AUTHOR: Sarah Johnson, CEO of TechCorp
  IMAGE "images/sarah.jpg"
    alt: "Sarah Johnson"

Flex Mode:

---
layout: testimonial
---
## What our customers say

> "This solution increased our productivity by 300% in just three months."
>
> **— Sarah Johnson, CEO of TechCorp**

![Sarah Johnson](images/sarah.jpg)

Validation Rules:

Should include quote and author information
Maximum 3 content elements
Focus on testimonial content

`call_to_action` - Call to Action Layout

Purpose: Drive specific user actions

What the styling does:

The whole slide takes the section slide’s background colour and its content is centred on both axes; the h1 loses the underline the base gives a content heading
Accepts columns (1-4), which turns the stacked content into a grid — useful when the closing slide lists several ways to get in touch — and align (left or center)

Strict Mode:

SLIDE call_to_action
  title: "Ready to Get Started?"
  subtitle: "Join thousands of satisfied customers"
  align: center
  TEXT
    [Start Free Trial](https://example.com/trial)
  TEXT
    [Learn More](https://example.com/docs)

Flex Mode:

---
layout: call_to_action
---

# Ready to Get Started?
## Join thousands of satisfied customers

[Start Free Trial](#primary){.btn-primary}
[Learn More](#secondary){.btn-secondary}

Validation Rules:

Must include action-oriented content
Should contain call-to-action elements
Maximum 3 elements for focus

Organization and Process Layouts

`timeline` - Timeline Layout

Purpose: Display chronological information and timelines

What the styling does:

The elements hang off a vertical rail drawn down the left edge
Each level-2 heading gets a dot on the rail, so the headings read as the moments in the sequence
The numbering is whatever you write: the layout adds no counter

Strict Mode:

SLIDE timeline
  title: "Project Roadmap"
  TABLE
    headers: ["Quarter", "Milestone", "Status"]
    rows: [
      ["Q1 2025", "Planning phase", "Completed"],
      ["Q2 2025", "Development", "In progress"],
      ["Q3 2025", "Testing", "Planned"]
    ]

Flex Mode:

---
layout: timeline
---

# Project Roadmap

- **Q1 2025** - Planning Phase ✅
- **Q2 2025** - Development 🔄
- **Q3 2025** - Testing 📅

Validation Rules:

Minimum 2 temporal events
Maximum 6 timeline elements
Focus on chronological content

`process` - Process/Methodology Layout

Purpose: Explain step-by-step processes and methodologies

What the styling does:

The same vertical rail as timeline, with a square marker instead of a dot — a sequence of steps rather than a sequence of dates
The numbering is whatever you write: the layout adds no counter

Strict Mode:

SLIDE process
  title: "Development Process"
  POINTS
    - 1. Requirements analysis
    - 2. Design and architecture
    - 3. Implementation
    - 4. Testing and QA
    - 5. Deployment

Flex Mode:

---
layout: process
---

# Development Process

1. **Requirements Analysis** - Understanding project needs
2. **Design & Architecture** - Planning the solution
3. **Implementation** - Building the product
4. **Testing & QA** - Ensuring quality
5. **Deployment** - Releasing to production

Validation Rules:

Minimum 2 sequential steps
Maximum 6 process steps
Focus on procedural content

Business and Marketing Layouts

`pricing` - Pricing/Plans Layout

Purpose: Display pricing tiers and plan comparisons

Styling:

Typed and validated like any other layout, but not styled yet: it renders like a content slide

Strict Mode:

SLIDE pricing
  title: "Choose Your Plan"
  TABLE
    headers: ["Plan", "Price", "Users", "Storage"]
    rows: [
      ["Basic", "$29/month", "5", "10 GB"],
      ["Pro", "$79/month", "50", "100 GB"]
    ]

Flex Mode:

---
layout: pricing
---

# Choose Your Plan

| Feature | Basic | Pro |
|---------|-------|-----|
| Price | $29/month | $79/month |
| Users | 5 | 50 |
| Storage | 10GB | 100GB |

Validation Rules:

Must include pricing information
Should contain plan comparison
Maximum 4 pricing tiers

`team` - Team Presentation Layout

Purpose: Introduce team members and organizational structure

Styling:

Typed and validated like any other layout, but not styled yet: it renders like a content slide

Strict Mode:

SLIDE team
  title: "Meet Our Team"
  TABLE
    headers: ["Name", "Role", "Contact"]
    rows: [
      ["Alice Johnson", "Lead developer", "alice@company.com"],
      ["Bob Smith", "Product manager", "bob@company.com"]
    ]

Flex Mode:

---
layout: team
---

# Meet Our Team

## Alice Johnson
**Lead Developer**
alice@company.com

## Bob Smith
**Product Manager**
bob@company.com

Validation Rules:

Should include member information with roles
Maximum 8 team members
Focus on person-related content

`dashboard` - Dashboard/Metrics Layout

Purpose: Display real-time interfaces and metrics

What the styling does:

The elements become a grid of cards; each level-3 heading is a card with its own background, radius and shadow
What structures the whole slide — a level-2 heading, a table, a chart, an image — spans the full width instead of becoming another card
Accepts the columns option (1-4) to fix the number of columns

Strict Mode:

SLIDE dashboard
  title: "Control Panel"
  columns: 2
  TABLE
    headers: ["Metric", "Value", "Change"]
    rows: [
      ["Total sales", "$2.4M", "+15%"],
      ["Active users", "18,420", "+7%"]
    ]

Flex Mode:

---
layout: dashboard
---

# Control Panel

## Key Metrics
- **Total Sales:** $2.4M (+15%)
- **Active Users:** 15,847 (+8%)
- **Conversion Rate:** 3.2% (+0.5%)

<<chart: line>>
  title: "Monthly Growth"
  data: [125, 145, 167, 189]

Validation Rules:

Should include metrics or charts
Maximum 6 dashboard elements
Focus on data visualization

`before_after` - Before/After Layout

Purpose: Show transformations and improvements

Styling:

Typed and validated like any other layout, but not styled yet: it renders like a content slide
It needs the template to group a heading with the elements that follow it, which it does not do today

Strict Mode:

SLIDE before_after
  title: "Transformation Results"
  TABLE
    headers: ["Before", "After"]
    rows: [
      ["Manual process taking 8 hours daily", "Automated process completed in 15 minutes"]
    ]

Flex Mode:

---
layout: before_after
---

# Transformation Results

## Before
Manual process taking 8 hours daily
- Time-consuming
- Error-prone
- Resource intensive

## After
Automated process completed in 15 minutes
- Efficient
- Accurate
- Cost-effective

Validation Rules:

Must have both “before” and “after” sections
Minimum 2 comparison elements
Maximum 4 total elements

Special Purpose Layouts

`feature_showcase` - Feature Showcase Layout

Purpose: Highlight product features and benefits

Styling:

Typed and validated like any other layout, but not styled yet: it renders like a content slide
It needs the template to group a heading with the elements that follow it, which it does not do today

Strict Mode:

SLIDE feature_showcase
  title: "Key Features"
  POINTS
    - 🚀 **Ultra fast** — processing in milliseconds
    - 🔒 **Secure** — end-to-end encryption

Flex Mode:

---
layout: feature_showcase
---

# Key Features

## 🚀 Ultra Fast
Processing in milliseconds

## 🔒 Secure
End-to-end encryption

## 📊 Analytics
Real-time insights

Validation Rules:

Should highlight at least 2 features
Maximum 6 feature highlights
Focus on feature-benefit content

`closing` - Closing Slide Layout

Purpose: Presentation conclusion and final thoughts

Styling:

Typed and validated like any other layout. The base stylesheet already dresses this slide type, so it has no separate layout CSS

Strict Mode:

SLIDE closing
  heading: "Thank You"
  subtitle: "Questions & Discussion"
  TEXT
    john@company.com

Flex Mode:

---
layout: closing
---

# Thank You
## Questions & Discussion

**Contact:** john@company.com
**LinkedIn:** /in/johnsmith

Validation Rules:

Should contain simple, conclusive content
Maximum 3 elements
Avoids complex elements

Layout Validation

ZiraDocs automatically validates slide content against layout requirements:

Validation Rules

A layout’s schema drives three kinds of check:

Forbidden elements - some layouts reject certain element types (LAYOUT_FORBIDDEN_ELEMENT, a warning)
Required properties - a missing one is LAYOUT_REQUIRED_PROPERTY; several layouts also have a dedicated rule with a better message (LAYOUT001 for title slides, LAYOUT003 for content, LAYOUT009 for hero)
Minimum/maximum elements - LAYOUT_MIN_ELEMENTS / LAYOUT_MAX_ELEMENTS. These are informational in flex mode and warnings in strict, because the count means different things in each dialect: in strict you declare every TEXT/POINTS yourself, while in flex consecutive paragraphs merge and a run of bullets is a single points element.

The schema used to also list “optional properties” and “allowed elements”. Neither was ever evaluated by anything, and both were removed rather than left to imply a check that did not happen (ziradocs/toolchain#256).

Validation Messages

The linter provides specific guidance when validation fails:

# Example validation messages
LAYOUT001: Title slides must have a 'heading' or a 'title' property      # error
LAYOUT003: Content slides must have a 'title' property                   # warning
LAYOUT011: Timeline slides should have at least 2 temporal events        # warning
LAYOUT015: Feature showcase slides should highlight at least 2 features  # warning

Most layout diagnostics are warnings or info. The ones that fail the build are LAYOUT001, LAYOUT004, LAYOUT008 and LAYOUT009 — see Slide Layouts for that table.

Mode Differences

Layout Specification

Strict Mode:

Layout specified in slide declaration: SLIDE layout_name
Example: SLIDE title, SLIDE comparison

Flex Mode:

Layout specified in a --- block placed immediately before the slide’s heading, not in the document frontmatter: a line layout: layout_name inside it
Options for that layout go in the same block — see Layout Properties

Syntax Comparison

Code Example in Strict Mode:

SLIDE code_example
  title: "My Code"
  CODE python
    print("Hello world")
  POINTS
    - Important point

Same Content in Flex Mode:

---
layout: code_example
---

# My Code

```python
print("Hello world")

Important point

### There is no automatic layout detection

Earlier versions of this page claimed flex mode infers a layout from the content — that a heading
plus an image becomes `hero`, or a table becomes `comparison`. **It does not.** A slide with no
`layout:` block is a `content` slide, whatever it contains.

The only thing flex derives on its own is the slide's title, from its first `#` heading.

## CSS Styling

The nine covered layouts each ship a stylesheet, loaded only when a slide in the deck actually uses
that layout. Every rule keys on the `data-slide-type` attribute:

```css
.slidelang-slide[data-slide-type="comparison"] .slidelang-content-elements {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
}

The attribute is the block type verbatim, which is why it is used instead of a class: it is the same string the linter validates and that travels in the AST’s JSON, and it is immune to the class-namespacing pass the generator runs over the template.

What those files do and do not do:

Colours come from theme tokens only, never a literal. Inside these files the tokens are written unprefixed (--primary-color, --bg-white, --bg-quote); the loader rewrites them on the way into the bundle, so what ships is var(--slidelang-primary-color). A theme redefines the prefixed name — --slidelang-primary-color — which is what every theme in the repo already declares.
They only arrange and colour. No animation, no typography scale of their own beyond what the layout needs, no layout-specific breakpoints — the responsive rules are the shared ones.
They lose to nothing by accident. A layout that declares a background is excluded from the content-slide chrome, so its own background is the one that applies.

The four layouts in the “not styled yet” row of Slide Layouts have no file; they render like a content slide.

Best Practices

Choose appropriate layouts - Match layout to content type
Follow validation rules - Address linter warnings promptly
Keep content focused - Respect element limits for clarity
Test responsiveness - Verify layouts work on all devices
Restyle through tokens - the layout CSS reads theme tokens, so a theme changes a layout’s colours without overriding its rules
Validate regularly - Run linter during development

CLI Integration

Layout validation works seamlessly with ZiraDocs CLI:

# Validate layouts during build
slidelang build presentation.slidelang

# Lint-only mode for layout checking
slidelang build --lint-only presentation.slidelang

# Debug layout detection
slidelang build presentation.slidelang --log-level debug

Common Patterns

Progressive Presentation Structure

SLIDE title          # Presentation introduction
SLIDE section        # Section introductions
SLIDE content        # Main content slides
SLIDE comparison     # Feature/option comparisons
SLIDE stats          # Supporting data
SLIDE call_to_action # Drive user action
SLIDE closing        # Conclusion and thanks

Technical Documentation Flow

SLIDE title          # API/Product introduction
SLIDE section        # Getting started section
SLIDE code_example   # Implementation examples
SLIDE dashboard      # Usage metrics/monitoring
SLIDE feature_showcase # Key capabilities
SLIDE pricing        # Plans and pricing
SLIDE closing        # Contact and next steps

Marketing Presentation Flow

SLIDE hero           # Eye-catching introduction
SLIDE feature_showcase # Product highlights
SLIDE testimonial    # Social proof
SLIDE before_after   # Transformation stories
SLIDE pricing        # Plans and offers
SLIDE call_to_action # Drive conversion
SLIDE closing        # Thank you and contact

Strict Mode Syntax - Using layouts in Strict Mode
Flex Mode Syntax - Using layouts in Flex Mode
FrontMatter Configuration - Layout configuration options
Advanced Elements - Complex content elements
Slide Layouts - The full list of recognized names, which have a schema, and which have styling
Themes & Styling - Visual customization

Examples

See the Specialized Layouts Examples directory for complete working examples of all layout types in both Strict and Flex modes.

💡 Pro Tip: Start with basic layouts (title, content, section) and gradually incorporate specialized layouts as your presentation complexity grows.

Specialized Layouts

Overview

Layout Types

Basic Layouts

title - Title Slide Layout

content - General Content Layout

section - Section Introduction Layout

Comparison and Analysis Layouts

comparison - Side-by-Side Comparison Layout

stats - Statistics and Data Layout

Technical and Content Layouts

code_example - Code Example Layout

testimonial - Testimonial Layout

call_to_action - Call to Action Layout

Organization and Process Layouts

timeline - Timeline Layout

process - Process/Methodology Layout

Business and Marketing Layouts

pricing - Pricing/Plans Layout

team - Team Presentation Layout

dashboard - Dashboard/Metrics Layout

before_after - Before/After Layout

Special Purpose Layouts

feature_showcase - Feature Showcase Layout

closing - Closing Slide Layout

Layout Validation

Validation Rules

Validation Messages

Mode Differences

Layout Specification

Syntax Comparison

Best Practices

CLI Integration

Common Patterns

Progressive Presentation Structure

Technical Documentation Flow

Marketing Presentation Flow

Related Documentation

Examples

`title` - Title Slide Layout

`content` - General Content Layout

`section` - Section Introduction Layout

`comparison` - Side-by-Side Comparison Layout

`stats` - Statistics and Data Layout

`code_example` - Code Example Layout

`testimonial` - Testimonial Layout

`call_to_action` - Call to Action Layout

`timeline` - Timeline Layout

`process` - Process/Methodology Layout

`pricing` - Pricing/Plans Layout

`team` - Team Presentation Layout

`dashboard` - Dashboard/Metrics Layout

`before_after` - Before/After Layout

`feature_showcase` - Feature Showcase Layout

`closing` - Closing Slide Layout