# Packaging

> How to lay out, name and zip a deck's files so MakoDeck accepts them: the folder, paths, allowed file types, limits, zipping pitfalls, images, data and media.

## Folder layout

```text
deck/
├── index.html          the deck: every slide, its CSS and the manifest
├── assets/
│   ├── logo.svg
│   └── team-photo.jpg
├── fonts/
│   ├── BrandSans-Regular.woff2
│   └── LICENSE.txt     the font's licence (.txt: a file without an extension is skipped)
└── data/
    └── orders.json
```

## Rules

- **Entry:** `index.html` (or `index.htm`) at the top of the ZIP — or, failing that, the only HTML file at the top. One wrapping folder is unwrapped (`deck/index.html` works), but not two.
- **Paths:** relative to the file that uses them — `assets/logo.svg`, `../fonts/x.woff2` from a CSS file in `css/`. Use relative paths only: a `/path` in HTML or CSS is rewritten when that file is in the upload, but a script's `fetch()` or `import` of a `/…` path never loads. No `C:\`, no `file://`, no `..` that climbs out of the folder.
- **Names:** no `%`, `?` or `#`, no backslashes, no control characters, no invisible ones (bidi controls, zero-width or tag characters; an emoji's own joiner is fine) in a file's or a folder's name — such a name refuses the whole ZIP, and a software file so named isn't attached — and no two names that differ only in upper/lower case. Match each file's name exactly, capitals included, wherever you refer to it.
- **Not allowed:** symbolic links, password-protected ZIPs, compression other than standard (store or deflate), and a top-level folder named `_mako` (the site's own).
- **Dropped, harmless:** `__MACOSX/`, `.DS_Store`, `Thumbs.db` and `desktop.ini` silently; other hidden files (names starting with `.`) and source maps (`.map`) with a warning. `.md` files are dropped unless a reveal.js section loads them.
- **Allowed file types:** HTML, CSS, JavaScript, JSON, images (PNG, JPEG, GIF, WebP, AVIF, SVG, ICO), audio and video (MP3, WAV, OGG, MP4, WebM), fonts (WOFF2, WOFF, TTF, OTF), PDF, TXT and CSV. Anything else is skipped with a warning.

## Limits

| Limit | Value | Applies to |
|---|---|---|
| Upload size | 100 MB | the file you hand over: a `.zip`, `.html` or `.pdf` |
| Files in a zip | 500 | files, not folders |
| Unzipped total | 250 MB | all the zip's files together |
| One file | 100 MB | any single file in the zip |
| Slides | 300 | in one deck (a PDF: pages) |
| One HTML file | 32 MB | the deck's `index.html` and any other HTML file |
| One stylesheet | 16 MB | each `.css` file and each `<style>` block |
| `#mako-manifest` | 64 KB | the JSON in the entry file |
| Speaker notes | 20,000 characters | per slide |
| Title | 300 characters | a slide's, or the deck's |

The PDF the site makes from the deck is dropped if it would pass 100 MB, so keep images sensible.

## Zipping

Zip the folder's contents, not the folder inside another folder: `cd deck && rm -f ../deck.zip && zip -r -X ../deck.zip . -x '.*' '*/.*'` (https://makodeck.com/ai/workflow.md has a Python alternative for when `zip` is missing). Then run `unzip -l deck.zip` and check:

- `index.html` is at the top, with no folder in front of it (or exactly one);
- every file the deck refers to is listed, at the same path and spelling;
- nothing private came along: `.env` files, notes, drafts, spreadsheets you worked from. Frozen data files the deck loads are fine.

Finder's **Compress** on macOS adds `__MACOSX/` — harmless.

## Images

- Bundle every image and refer to it with a relative path: `<img src="assets/team-photo.jpg" alt="…">`. Remote images never load.
- Use images you have the right to use: the client's own, ones they supplied, or openly licensed ones (note the licence).
- Size them for a 1920×1080 slide: at most 3840 px on the long edge, usually far less. The site re-encodes PNG, JPEG and WebP files over 300 KB (at most 3840 px on the long edge, as WebP under the same name), keeping the result only if it saves at least 20%; PNG diagrams stay lossless unless that costs twice the size.
- Prefer SVG for icons and diagrams (logos: https://makodeck.com/ai/brand-and-design.md). An SVG shown with `<img>` can't load fonts: convert its text to outlines, or put the SVG inline in the page.
- `data:` images work, which is how a single-file deck carries small ones.

## Data files

Put JSON or CSV beside the page and load it with a relative URL: `fetch("data/orders.json")`. The data is frozen at upload; to update it, the person replaces the deck. A file opened straight from disk (`file://`) can't `fetch` — preview through a local server (https://makodeck.com/ai/workflow.md).

## Video and audio

Bundle MP4, WebM, MP3, WAV or OGG files and play them with `<video>` or `<audio>` and relative paths. Autoplay only when muted (`<video autoplay muted loop playsinline>`); otherwise give the presenter controls. Keep them short: every viewer downloads them.

## Files beside the deck

A ZIP carries only web files. When the deck comes with other files people may download — 3D models, notebooks, source code, scenes, data sets — the person uploads the unzipped folder with **Choose a folder**: the web files become the deck, and the rest become attachments the author allows for download under the deck's **Settings** → **Files** (https://makodeck.com/ai/interactive.md).