# Floe

> A browser-based slide deck editor. Write markdown, get a live preview, present fullscreen, export to HTML/PDF.

## Slide Syntax

Slides are separated by `---` (three or more dashes) on its own line.

```
# First Slide

Hello world

---

# Second Slide

More content
```

### Code block edge case

`---` inside fenced code blocks (``` or ~~~) is ignored and does NOT create a slide break. The parser tracks fence open/close state.

## Front-Matter Schema

### Global Config

Place YAML at the very top of the document (before the first `---`). All fields are optional.

| Field      | Type   | Allowed values  | Default |
|------------|--------|-----------------|---------|
| theme      | string | light, dark     | light   |
| transition | string | fade, none      | fade    |
| ratio      | string | 16:9, 4:3       | 16:9    |
| title      | string | any text        | —       |

Example:

```
theme: dark
transition: fade
ratio: 16:9
title: My Presentation
---
# First slide content
```

### Per-Slide Config

Place a YAML block immediately after a `---` separator, before the slide content. The config block must be followed by another `---` separator before the slide content. All fields are optional; unset fields inherit from global config.

| Field      | Type   | Allowed values          | Default         |
|------------|--------|-------------------------|-----------------|
| layout     | string | default, center         | default         |
| background | string | URL to image            | —               |
| transition | string | fade, none              | global setting  |
| class      | string | CSS class name(s)       | —               |

Example:

```
---
layout: center
background: https://example.com/hero.jpg
---
# Centered Slide Title
```

## Themes

### light
White background, dark text. Code blocks use the github-light Shiki theme. This is the default.

### dark
Dark background (#1a1a2e), light text. Code blocks use the github-dark Shiki theme.

## Layouts

### default
Standard content layout. Content flows top-to-bottom with normal prose styling. Suitable for body text, bullet lists, and code blocks.

### center
Content is vertically and horizontally centered. Good for title slides, section dividers, quotes, or single-point emphasis slides.

## Multi-Column Layout

Split a slide into side-by-side columns using `|||` (three pipe characters) on its own line. Each `|||` creates a new column.

```
# Left Column

Content for the left side

|||

# Right Column

Content for the right side
```

- Multiple `|||` separators create 3+ columns (all equal width)
- `|||` inside fenced code blocks is treated as literal text, not a separator
- Columns work with both `default` and `center` layouts — layout controls vertical alignment, columns control horizontal splitting
- Remove columns by deleting the `|||` line

### Example: Three columns

```
Point A

|||

Point B

|||

Point C
```

## Code Blocks

### Syntax Highlighting

Fenced code blocks are highlighted with Shiki. Specify the language after the opening fence:

````
```typescript
const greeting = "hello";
```
````

Supported languages: javascript, typescript, jsx, tsx, html, css, json, markdown, python, rust, go, bash, shell, yaml, sql, c, cpp, java.

If a language is not specified or not supported, the block renders as plain text.

### Stepped Highlights

Highlight specific lines with stepped animation (in presentation mode). Add a highlight spec in curly braces after the language:

````
```typescript {1-3|5|all}
const a = 1;    // step 1: lines 1-3 highlighted
const b = 2;
const c = 3;

const d = 4;    // step 2: line 5 highlighted
const e = 5;    // step 3: all lines highlighted
```
````

Syntax:
- Numbers: `{5}` highlights line 5
- Ranges: `{1-3}` highlights lines 1 through 3
- Comma-separated: `{1,3,5}` highlights lines 1, 3, and 5
- Combined: `{1-3,5}` highlights lines 1-3 and 5
- Pipe for steps: `{1-3|5|all}` creates 3 animation steps
- `all` highlights every line

In presentation mode, arrow keys advance through highlight steps before moving to the next slide. In the preview pane, highlight stepping is skipped (slide-to-slide only).

## Safe-Area Recommendations

These are approximate visible content limits before overflow. They are advisory, not enforced.

### 16:9 ratio
- Body text: ~10-12 lines
- Code blocks: ~12-15 lines
- Mixed (heading + body + code): keep total under 10 elements

### 4:3 ratio
- Body text: ~14-16 lines
- Code blocks: ~16-18 lines
- Mixed (heading + body + code): keep total under 14 elements

Tips:
- Headings and spacing consume vertical space — account for them
- A single large code block is safer than body text + code combined
- Prefer splitting content across slides over cramming

## Presentation Mode

Enter from the editor via the Present button. Controls:

- **Next slide / highlight step:** Click, Space, Right arrow, Down arrow, Page Down
- **Previous slide / highlight step:** Shift+Click, Left arrow, Up arrow, Page Up, Backspace
- **Exit:** Esc

Clicks on links or buttons inside a slide do not advance — presenters can still interact with slide content. Slide transitions use a fade-over (new slide fades in on top of the previous one) so there is no flash between slides.

## Export

### HTML
Exports a self-contained HTML file with all CSS inlined, keyboard navigation (arrow keys, space, escape), click-to-fullscreen, and a print stylesheet for PDF conversion.

### PDF
Uses the browser's print dialog (Cmd/Ctrl+P) on the exported HTML. The print stylesheet formats slides as individual pages.

## Complete Example

```
theme: dark
ratio: 16:9
title: Demo Deck
---
layout: center
---
# Welcome to Floe

Write slides in markdown

---

## Features

- Live preview
- Syntax highlighting
- Keyboard navigation
- HTML/PDF export

---

## Code Example

```python {1-2|4-5|all}
def greet(name):
    return f"Hello, {name}!"

result = greet("World")
print(result)
```

---

## Side by Side

Left content here

|||

Right content here

---
layout: center
---

# Thank You
```