File Structure

Understanding the directory structure created by the Buttondown CLI

The Buttondown CLI creates a well-organized directory structure to manage your newsletter content locally.

Directory Overview

When you run buttondown pull, the CLI creates the following structure:

my-newsletter/
├── .buttondown.json      # Sync state and configuration
├── emails/               # Newsletter emails as Markdown files
│   ├── welcome-email.md
│   ├── issue-001.md
│   └── issue-002.md
├── media/                # Images and media files
│   ├── header-image.png
│   ├── chart.jpg
│   └── logo.svg
├── automations/          # Email automations
│   └── automations.json
├── newsletter/           # Newsletter settings
│   └── newsletter.json
└── snippets/             # Reusable content snippets
    └── snippets.json

Core Directories

emails/

Contains all your newsletter emails as Markdown files with YAML frontmatter.

• File naming: Each email is saved as {slug-or-id}.md
• Format: Markdown with YAML frontmatter (see Email Format)
• Purpose: Main content for your newsletters

Emails use the slug field for the filename if available, otherwise they fall back to the email’s id.

media/

Stores all images and media files downloaded from Buttondown.

• File naming: Original filename from Buttondown (e.g., header-image.png)
• Supported formats: PNG, JPG, GIF, SVG, WebP
• Usage: Referenced in emails using relative paths

Example reference in an email:

![My chart](../media/chart.jpg)

Other Resource Directories

The CLI also syncs additional Buttondown resources:

automations/

Email automation workflows

newsletter/

Newsletter settings and configuration

snippets/

Reusable content snippets

State Management File

.buttondown.json

This file tracks the sync state and is automatically managed by the CLI.

{
  "syncedImages": {
    "img_abc123": {
      "id": "img_abc123",
      "localPath": "/absolute/path/to/my-newsletter/media/header.png",
      "url": "https://buttondown.s3.amazonaws.com/images/abc123.png",
      "filename": "header.png"
    }
  }
}

Key responsibilities:

syncedImages · object

Maps image IDs to their local paths and remote URLs. This allows the CLI to:

• Convert absolute URLs to relative paths when pulling
• Convert relative paths to absolute URLs when pushing
• Avoid re-uploading images that are already synced
• Track which images belong to your newsletter

Do not manually edit .buttondown.json unless you know what you’re doing. The CLI relies on this file to track sync state and prevent duplicate uploads.

How Files Are Created

On Pull

From src/commands/pull.tsx:83-162:

1. Create directories

   The CLI creates the base directory structure with mkdir recursive mode.

2. Download resources

   Syncs automations, newsletter settings, and snippets first.

3. Download images

   Fetches all images from Buttondown and saves them to media/.

4. Download emails

   Fetches emails and converts absolute image URLs to relative paths.

5. Update state

   Writes the sync state to .buttondown.json.

On Push

From src/commands/push.tsx:84-184:

1. Read local files

   Scans the directory for modified files.

2. Upload new images

   Any images referenced in emails that aren’t in .buttondown.json are uploaded.

3. Convert image paths

   Replaces relative image paths with absolute URLs before pushing to Buttondown.

4. Upload changes

   Only emails that have changed are uploaded to Buttondown.

5. Update state

   Updates .buttondown.json with newly uploaded images.

Directory Location

By default, the CLI uses a ./buttondown directory in your current working directory.

You can specify a different location:

buttondown pull --directory=./my-custom-location
buttondown push --directory=./my-custom-location

Use the same --directory flag for both pull and push commands to ensure consistency.

Version Control

When using Git or other version control systems:

Do commit:

• emails/ - Your newsletter content
• media/ - Images and media files (if not too large)
• automations/, newsletter/, snippets/ - Configuration files

Consider ignoring:

• .buttondown.json - Contains absolute paths specific to your machine
• Large media files (add to .gitignore and use Git LFS if needed)

Example .gitignore:

.buttondown.json
media/*.mp4
media/*.mov