# FolderPress Content Guide

> This folder is managed by FolderPress. Markdown files here become a live website.
> Save a file, it's published. Rename it, the URL updates. Delete it, it's gone.

## Folder Structure

```
posts/           → Blog posts (URL: /posts/slug)
decks/           → Slide presentations (URL: /decks/slug)
*.md (root)      → Standalone pages (URL: /slug)
```

Subfolders become URL paths: `posts/recipes/pasta.md` → `/posts/recipes/pasta`

## Drafts

End a filename with `.draft.md` to keep it hidden. Remove the suffix to publish.

```
posts/ideas.draft.md     → hidden
posts/ideas.md           → published
```

## Frontmatter

Optional YAML block at the top of any file:

```yaml
---
title: Override Title        # Default: first H1 or filename
published_at: 2026-04-12     # Default: now (omit for auto)
description: Short summary   # Used in meta tags and feeds
noindex: true                # Hide from search engines
newsletter: false            # Skip newsletter delivery
---
```

All fields are optional. If omitted, sensible defaults apply.

## Conventions

**Title** — resolved in this order:
1. Frontmatter `title` field
2. First `# Heading` in the document
3. Filename (numeric prefixes like `01-` are stripped for pages)

The `# Heading` always renders in the body. If you also set `title` in frontmatter, both appear — use one or the other, not both.

**Slug / URL** — derived from the filename, not the title:
- `posts/hello-world.md` → `/posts/hello-world`
- `posts/2024/year-recap.md` → `/posts/2024/year-recap`
- Spaces become hyphens, special characters are stripped, everything is lowercased
- Choose filenames carefully — they ARE your permanent URLs

**Published date** — resolved in this order:
1. Frontmatter `published_at` / `publishedAt` / `date`
2. If omitted, defaults to the moment the file is first synced
3. Set a future date to schedule publication

**Page ordering** — Pages (root-level `.md` files) strip numeric prefixes:
- `01-about.md` → slug `about`, but sorted first
- `02-contact.md` → slug `contact`, sorted second
- Posts and decks do NOT strip numeric prefixes

## Markdown Features

Standard GitHub Flavored Markdown plus:

- **Code blocks** — Syntax highlighted (specify language after ```)
- **Math** — Inline `$E=mc^2$` or block `$$\sum_{i=1}^{n} x_i$$`
- **Tables** — GFM pipe tables
- **Smart typography** — Curly quotes, em-dashes, ellipsis
- **Embeds** — Paste a YouTube or X/Twitter URL on its own line
- **Iframes** — YouTube, Vimeo, Spotify, CodePen, Loom, Google Maps, Figma
- **Images** — `![alt](url)` with lazy loading. Use HTTPS URLs or relative paths.

## Slide Decks

Files in `decks/` are presentations. Separate slides with `---` (blank line before and after).

### Layouts (auto-detected)

| Content                         | Layout     |
|---------------------------------|------------|
| `# Heading` alone              | statement  |
| `# Heading` + short subtitle   | cover      |
| Only blockquotes                | quote      |
| Short text with a number        | big-number |
| Single image                    | full-bleed |
| Everything else                 | default    |

### Background Images

```markdown
![bg](photo.jpg)                  # Fullscreen cover
![bg contain](diagram.png)        # Fit without cropping
![bg left](photo.jpg)             # Image left, text right
![bg right contain](chart.png)    # Image right, text left
```

### Progressive Reveal

```markdown
- First point
<!-- click -->
- Second point (appears on next advance)
<!-- click -->
- Third point
```

## Ignored Files

These are never published:

- `_filename.md` — underscore prefix
- `.hidden.md` — dot prefix
- Dropbox conflicted copies
- Files > 1 MB
- Files in `.git/`, `node_modules/`, `.cache/` directories

## Tips

- One file = one post/page/deck. No config files needed.
- The filename IS the URL slug. Choose it carefully.
- Nest folders freely — the path becomes the URL path.
- Images referenced as relative paths must be HTTPS URLs (Dropbox doesn't serve local images directly).