# Welcome to Markdeck 3D

A minimal, distraction-free presentation tool.
Write slides in plain Markdown — no plugins, no accounts, no internet required.

**Navigate:** `→` next section · `↓` sub-slide · `Space` next slide

-- duration: 30s
Everything stays local in your browser. Nothing is uploaded anywhere.

---

## Getting Started

1. Click **Choose delimiters** to confirm how your slides are separated
2. Load your Markdown — either **Import MD file** (local) or **Load from URL** (remote)
3. Navigate with the **arrow keys** or the on-screen controls

That's it. Your presentation is ready.

-- duration: 45s
The app parses your Markdown file entirely in the browser using the marked.js library.

---

## Load from URL

Click **Load from URL** in the start screen to fetch a Markdown file directly from the web.

Paste any public `https://` address into the input and click **Load** (or press `Enter`):

- Raw GitHub files: `https://raw.githubusercontent.com/user/repo/main/slides.md`
- GitHub Gists: `https://gist.githubusercontent.com/...`
- Any publicly accessible `.md` file

The file is fetched in your browser. The server must allow cross-origin requests (CORS).
Press `Esc` or click **✕** to dismiss without loading.

-- duration: 45s
Raw GitHub URLs always support CORS. If you get a network error from another host, check that the server sends an Access-Control-Allow-Origin header.

---

# Writing Slides

Everything you need to structure your Markdown file as a slide deck.

-- duration: 15s
This section covers delimiters, speaker notes, timing, and frontmatter.

---

## Slide Delimiters

Slides are separated by a delimiter on its own line.

The default delimiter is `---`:

```
Slide one content

---

Slide two content
```

Other options: `===`, a custom string, or **# H1** mode where each top-level heading starts a new slide.
Change the delimiter anytime via the **Choose delimiters** panel.

-- duration: 1m
The delimiter must be on its own line with no surrounding text.
In H1 mode, the heading text becomes the slide title and the delimiter is implicit.

---

## Speaker Notes

Add speaker notes after the notes delimiter `--`:

```
Slide content visible to the audience

--
These notes are only shown in the notes panel.
They can span multiple lines.
```

Alternatively, use `notes:` as the notes delimiter. Both options are available in the **Choose delimiters** panel.

Notes are hidden from the main slide view and only visible in the speaker notes area.

-- duration: 45s
Speaker notes support full Markdown formatting — bullet points, bold, code, etc.

---

## Slide Timing

Add a duration hint directly on the notes delimiter line:

- `-- duration: 2m` — minutes
- `-- duration: 90s` — seconds
- `-- duration: 1m30s` — minutes and seconds combined
- `-- duration: 2:00` — colon notation also works

Once durations are set, toggle the **per-slide progress bar** with the hourglass button, and the **global session timer** with the timer button. Both are in the bottom toolbar.

-- duration: 1m
Durations are optional — you can add them to some slides and leave others without.
The global bar only appears when at least one slide has a duration set.

---

## Frontmatter

Add YAML frontmatter at the very top of your Markdown file to set metadata:

```
---
title: My Presentation
author: Jane Smith
date: 2026-01-01
theme: ds-light    # optional, see Themes
mode: 3d           # optional, opt in to 3D mode
---

## First Slide
```

Frontmatter is parsed and stored but does not appear as slide content.

-- duration: 20s
The frontmatter block must start on the very first line and be closed by a second --- before any slide content. `theme:` and `mode:` are optional fork-specific extensions.

---

## Themes

Pick a theme from the **tune** settings panel, or set one in the deck frontmatter:

```yaml
---
theme: ds-light    # ds-dark, ds-frost, ds-aurora, tf-horizon
---
```

Five themes ship with the app:

- `ds-light` — Dynamic Skillset, Nord Snow Storm + brand blue
- `ds-dark` — Dynamic Skillset, Polar Night + Frost
- `ds-frost` — Dynamic Skillset, cool blue light
- `ds-aurora` — Dynamic Skillset, warm Nord accents
- `tf-horizon` — TechFreedom, cream paper + navy + amber

A theme overrides headings, body fonts, accent colour, code-block style, and blockquote rule in one move. Themes work the same in 2D and 3D mode.

-- duration: 45s
Themes are CSS-variable driven. Setting one applies a body class which a stylesheet block uses to paint the deck. They override the simpler bg / font controls below them in the settings panel.

---

## 3D mode

Add `mode: 3d` to the deck frontmatter to render the deck on an impress.js stage. Each slide can carry its own position, rotation, and scale via a `+++` block at its top:

```markdown
---
title: My 3D deck
mode: 3d
theme: ds-light
---

+++
x: 0
y: 0
+++

## First slide

---

+++
x: 1500
y: -800
rotate-y: 90
scale: 1.2
+++

## Second slide
```

Recognised keys: `x`, `y`, `z`, `rel-x`, `rel-y`, `rel-z`, `rotate` (alias for `rotate-z`), `rotate-x`, `rotate-y`, `rotate-z`, `scale`, `transition-duration`, `id`, `class`. Slides without coordinates are auto-positioned in a horizontal line.

In 3D mode press `O` to zoom out to an overview of the whole deck, then click any step to fly to it.

-- duration: 1m
3D mode bundles impress.js (1.1.0) under the hood. Touch swipe is supported as well as keyboard and mouse.

---

## Local images

Select your `.md` file and any companion image files together in the picker, or drag a folder onto the slide area. Relative `![alt](image.png)` references then resolve to the dropped files automatically.

```markdown
![diagram](diagram.png)
![hero](images/hero.jpg)
```

The match is forgiving: bare filename, relative path, or a tail-matched parent path all work.

-- duration: 30s
The fork builds an in-memory map of filename → blob URL after every upload, then rewrites image src attributes after each render. URLs are revoked when a new deck is loaded.

---

# Navigating

Move through your deck efficiently — with keyboard shortcuts, the overview, and the route map.

-- duration: 15s
This section covers navigation keys, the slide overview, the route map, and search.

---

## Navigation

| Action | Key or control |
|---|---|
| Move to next section | `→` |
| Move to previous section | `←` |
| Move to sub-slide below | `↓` |
| Move to sub-slide above | `↑` |
| Next slide (linear) | `Space` `Page Down` |
| Previous slide (linear) | `Page Up` |
| Toggle nav arrows | **⇄** button |

Slides starting with an `# H1` heading each form a **section** (column). Slides within a section are sub-slides (rows). The vertical dot strip on the right edge tracks your position within a section.

-- duration: 45s
Keyboard navigation is the fastest way to move through slides during a presentation.
The vertical nav strip only appears when the current section has more than one sub-slide.

---

## Slide Overview

Press `O` or click the **grid_view** button to open the slide overview.

- All slides are shown as thumbnail cards, grouped by section
- The active slide is highlighted
- Click any card to jump directly to that slide
- Press `O` or `Esc` to close

-- duration: 30s
The overview is the quickest way to jump to any slide at a glance, especially in long presentations.

---

## Route Map

Press `Alt M` to toggle the **route map** — a compact track of all slides along the bottom.

- Each dot represents one slide; section boundaries are marked with a tick
- The current slide is highlighted with a pulsing dot
- Click any dot to jump directly to that slide
- Dots with a duration show a small timer badge
- Slides with a title show a short label below the dot

-- duration: 30s
The route map is especially useful in long presentations to keep track of where you are.

---

## Search

Press `Ctrl F` (or `Cmd F` on Mac) to open the search bar.

- Type to highlight matching text across all slides
- Use `↑` `↓` to jump between matches
- The slide view navigates automatically to each match

Press `Esc` or click **✕** to close the search bar.

-- duration: 30s
Search is case-insensitive and works across slide content only — not speaker notes.

---

# Interface

Customise how the app looks and behaves during your presentation.

-- duration: 15s
This section covers fullscreen, zoom, the outline, and appearance settings.

---

## Fullscreen

Press `F` or click the **fullscreen** button (bottom right) to enter fullscreen mode.

Press `F` again (or `Esc` from fullscreen) to exit.

Fullscreen hides the browser chrome for a distraction-free presentation experience.

-- duration: 15s
Fullscreen is supported in all modern browsers. On some systems, the first use prompts for permission.

---

## Zoom

Click the **zoom_in** button to open the zoom panel.

- Use **–** and **+** to step the content scale from 80% to 150%
- Click **100%** to reset to the default size
- The current zoom level is shown in the panel

Zoom is saved automatically alongside your other settings.

-- duration: 20s
Zoom scales the slide content without affecting the layout or overflow behaviour.

---

## Plan / Outline

Click the **toc** (table of contents) button to open the Plan panel.

The panel lists all slides that have an `# H1` heading. Click any entry to jump directly to that section.

-- duration: 20s
The outline is built automatically from H1 headings. It updates as you navigate.

---

## Appearance Settings

Click the **tune** button (bottom right) to open the settings panel.

**Background** — choose from 6 soft colour palettes:
Cloud · Warm · Sage · Slate · Lavender · Dusk

**Font** — choose from 4 system typefaces:
Sans-serif · Serif · Rounded · Monospace

Click **Reset to defaults** to restore the original appearance.
Settings are saved automatically and restored on your next visit.

-- duration: 45s
All settings are stored in your browser's localStorage — they persist across reloads but are local to your machine.

---

# Editing & Exporting

Author your deck inside the app and export it as a self-contained HTML file.

-- duration: 15s
This section covers the split-view editor and the HTML export feature.

---

## Split-View Editor

Click the **vertical_split** button to open the built-in Markdown editor alongside the slide preview.

- Edit the Markdown source directly in the left panel
- The slide preview updates automatically as you type
- Click **Download .md** in the editor header to save the current source as a file

The split editor is useful for authoring and refining slides without switching applications.

-- duration: 30s
The editor shows the raw Markdown for the entire deck, not just the current slide.

---

## Export as HTML

Click the **download** button (visible once a deck is loaded) to export the current presentation as a self-contained HTML file.

The exported file includes all slides, settings, and the app runtime — it can be opened in any browser without an internet connection.

-- duration: 20s
The export captures your current background and font settings as defaults in the exported file.

---

# Markdown Features

What you can put inside a slide — beyond basic text.

-- duration: 15s
This section covers the full range of content types supported in slides.

---

## Markdown Support

Full **CommonMark** Markdown is supported:

- Headings (`#` `##` `###`)
- **Bold**, *italic*, ~~strikethrough~~, `inline code`
- Ordered and unordered lists
- Blockquotes, tables, horizontal rules
- Fenced code blocks with syntax hints
- Images — automatically constrained to fit the slide
- Footnotes[^1]

[^1]: Footnote definitions are placed at the bottom of a slide's content.

-- duration: 45s
Images are scaled to a maximum of 100% width and 65% viewport height, preserving aspect ratio. No manual sizing needed.

---

## Code Blocks

Fenced code blocks render with a clean monospace style:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

Language hints after the opening ` ``` ` are supported. Use ` ```mermaid ` for diagrams.

-- duration: 30s
Code blocks scroll horizontally if the content is wider than the slide.

---

## Mermaid Diagrams

Use a fenced code block with the `mermaid` language hint to render diagrams:

````
```mermaid
flowchart LR
  A[Write] --> B[Present]
```
````

Flowcharts, sequence diagrams, Gantt charts, and all other Mermaid diagram types are supported.

-- duration: 30s
Mermaid diagrams are rendered entirely in the browser — no server required.

---

## Math (KaTeX)

Write LaTeX-style math inline with `$...$` or as a display block with `$$...$$`:

Inline: $E = mc^2$

Display:

$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

-- duration: 30s
Math is rendered by KaTeX, a fast client-side LaTeX engine. Standard LaTeX math syntax is supported.

---

## Callouts

Use Obsidian-style callout syntax to create styled alert boxes:

```
> [!note]
> This is a note callout.

> [!tip] Custom title
> A tip with a custom title.

> [!warning]
> Something to watch out for.
```

Available types: `note` · `tip` · `info` · `success` · `warning` · `danger` · `question` · `example` · `quote`

Add `-` after the type (e.g. `[!note]-`) to start the callout collapsed.

-- duration: 45s
Callout type names match Obsidian conventions. Many aliases are also supported (e.g. hint, caution, bug).

---

## QR Codes

Generate QR codes directly in a slide using either syntax:

**Image syntax** (alt text starts with `qr`):
```
![qr](https://example.com)
```

**Div syntax** (for more control):
```html
<div data-qr="https://example.com" data-size="200"></div>
```

The QR code is rendered in the browser using the qrcodejs library.

-- duration: 30s
The data-size attribute controls the pixel dimensions. Default is 200 × 200 px.

---

# Reference

A quick reference for examples, shortcuts, and tips.

-- duration: 15s
This section has a complete slide example, a keyboard shortcut table, and practical tips.

---

## A Complete Slide Example

Here is a full slide with all elements combined:

```markdown
## My Slide Title

Some **bold** and *italic* text.

- Point one
- Point two

---  ← slide delimiter

-- duration: 1m30s  ← notes delimiter + duration
Speaker notes go here.
```

-- duration: 1m
The delimiter line must contain only the delimiter characters — no spaces before or after on the same line.

---

## Keyboard Reference

| Action | Shortcut |
|---|---|
| Next / Previous section | `→` / `←` |
| Sub-slide below / above | `↓` / `↑` |
| Next (linear) | `Space` `Page Down` |
| Previous (linear) | `Page Up` |
| Slide overview | `O` |
| Route map | `Alt M` |
| Search | `Ctrl F` / `Cmd F` |
| Fullscreen | `F` |
| Close any panel | `Esc` |

-- duration: 30s
All keyboard shortcuts work when focus is on the slide — not when a text input is active.

---

## Tips

- Keep slides **focused** — one idea per slide works best
- Use `---` on its own line; extra spaces will break detection
- Speaker notes are a great place for **talking points** and **statistics**
- The `# H1` delimiter mode works well for existing Markdown documents and creates sections automatically
- Imported files stay **local** — nothing is uploaded; URL-loaded files are fetched directly from their host
- The **split editor** lets you author and preview at the same time — download the result when done
- Use `O` during a presentation to jump to any slide instantly

-- duration: 1m
You can re-import a file at any time — the app will reload from the beginning.

---

## Ready to Present

Load your own Markdown file and start presenting.

*Write in Markdown. Present anywhere.*

-- duration: 15s
This slide deck was itself written in Markdown and presented using this app.