bunki 0.6.0 → 0.7.0

package/README.md

@@ -1,45 +1,60 @@
 # Bunki
 
-# Bunki
+[![CI](https://github.com/kahwee/bunki/actions/workflows/ci.yml/badge.svg)](https://github.com/kahwee/bunki/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/kahwee/bunki/badge.svg?branch=main)](https://coveralls.io/github/kahwee/bunki?branch=main)
+[![npm version](https://badge.fury.io/js/bunki.svg)](https://badge.fury.io/js/bunki)
 
-Fast static site generator for blogs/docs built with Bun. Core features: Markdown + frontmatter, tags, year archives, pagination, RSS, sitemap, secure sanitized HTML, syntax highlighting, optional PostCSS pipeline, image uploading (S3/R2), tiny Nunjucks templates.
+Fast static site generator for blogs and documentation built with Bun. Supports Markdown + frontmatter, tags, year-based archives, pagination, RSS feeds, sitemaps, secure HTML sanitization, syntax highlighting, PostCSS pipelines, media uploads (images & videos to S3/R2), incremental uploads with year filtering, and Nunjucks templating.
 
 ## Install
 
+Requires **Bun v1.3.0+** (recommended) or Node.js v18+
+
 ```bash
-bun install bunki        # add locally
-bun install -g bunki     # or global
-npm i bunki              # Node (>=18)
-```
+# Install globally with Bun
+bun install -g bunki
 
-Requires Bun >= 1.2.21 (recommended runtime).
+# Or with npm
+npm install -g bunki
+
+# Or in your project
+bun install bunki
+```
 
 ## Quick Start
 
 ```bash
-bunki init
-bunki new "Hello World" --tags web,notes
-bunki generate
-bunki serve  # http://localhost:3000
+bunki init                                    # Create new site
+bunki new "My First Post" --tags web,notes    # Add content
+bunki generate                                # Build static site
+bunki serve --port 3000                       # Preview locally
 ```
 
-## Minimal Config (bunki.config.ts)
+This creates a fully functional site with Markdown content, responsive templates, and all assets in `dist/`.
 
-```ts
+## Configuration
+
+Create `bunki.config.ts` in your project root:
+
+```typescript
 import { SiteConfig } from "bunki";
+
 export default (): SiteConfig => ({
   title: "My Blog",
-  description: "Thoughts",
+  description: "My thoughts and ideas",
   baseUrl: "https://example.com",
   domain: "example.com",
+
+  // Optional: PostCSS/Tailwind CSS support
   css: {
     input: "templates/styles/main.css",
     output: "css/style.css",
     postcssConfig: "postcss.config.js",
     enabled: true,
-  }, // optional
+  },
+
+  // Optional: Image upload to Cloudflare R2 or S3
   s3: {
-    // optional image upload
     accessKeyId: process.env.R2_ACCESS_KEY_ID || "",
     secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || "",
     bucket: process.env.R2_BUCKET || "",
@@ -50,37 +65,54 @@ export default (): SiteConfig => ({
 });
 ```
 
-## Frontmatter
+## Content & Frontmatter
+
+Create Markdown files in `content/YYYY/` (e.g., `content/2025/my-post.md`):
 
 ```markdown
 ---
 title: "Post Title"
 date: 2025-01-15T09:00:00-07:00
 tags: [web, performance]
-excerpt: Optional summary
+excerpt: "Optional summary for listings"
 ---
+
+# Post Title
+
+Your content here with **markdown** support.
+
+![Image alt text](/images/my-image.jpg)
+
+<video controls width="640" height="360">
+  <source src="video.mp4" type="video/mp4">
+  Your browser does not support HTML5 video.
+</video>
 ```
 
-Optional tag descriptions: `src/tags.toml`:
+Optional: Define tag descriptions in `src/tags.toml`:
 
 ```toml
-performance = "Speed & optimization"
-web = "General web dev"
+performance = "Performance optimization and speed"
+web = "Web development and technology"
 ```
 
-## CSS (Tailwind example)
+## CSS & Tailwind
+
+To use Tailwind CSS:
 
 ```bash
 bun add -D tailwindcss @tailwindcss/postcss @tailwindcss/typography
 ```
 
-`postcss.config.js`:
+Create `postcss.config.js`:
 
-```js
-module.exports = { plugins: [require("@tailwindcss/postcss")] };
+```javascript
+module.exports = {
+  plugins: [require("@tailwindcss/postcss")],
+};
 ```
 
-`templates/styles/main.css`:
+Create `templates/styles/main.css`:
 
 ```css
 @tailwind base;
@@ -88,541 +120,533 @@ module.exports = { plugins: [require("@tailwindcss/postcss")] };
 @tailwind utilities;
 ```
 
-Processed automatically during `bunki generate`.
+CSS is processed automatically during `bunki generate`.
+
+## Image Management
+
+### Overview
+
+The `images:push` command uploads local media (images and videos) to Cloudflare R2, AWS S3, or any S3-compatible storage provider. Media files are organized by year in the `images/` directory and uploaded with their full directory structure preserved.
+
+**Supported formats:**
 
-## Images
+- **Images:** JPG, JPEG, PNG, GIF, WebP, SVG
+- **Video:** MP4
 
-Env vars (R2 / S3):
+### Directory Structure
+
+Organize images by year and post slug:
 
 ```
-R2_ACCESS_KEY_ID=...
-R2_SECRET_ACCESS_KEY=...
-R2_BUCKET=...
-R2_ENDPOINT=...
-R2_PUBLIC_URL=https://cdn.example.com
+images/
+├── 2023/
+│   ├── post-slug-1/
+│   │   ├── image-1.jpg
+│   │   └── image-2.png
+│   └── post-slug-2/
+│       └── photo.webp
+├── 2024/
+│   └── travel-guide/
+│       ├── paris-1.jpg
+│       ├── london-2.jpg
+│       ├── tokyo-3.png
+│       └── travel-vlog.mp4
+└── 2025/
+    └── new-post/
+        ├── screenshot.jpg
+        └── demo-video.mp4
 ```
 
-Upload:
+The directory structure is preserved when uploading to cloud storage.
 
-```bash
-bunki images:push --images ./images --output-json image-map.json
-```
+### Configuration
+
+Add S3/R2 configuration to `bunki.config.ts`:
 
-## Programmatic
+```typescript
+import { SiteConfig } from "bunki";
+
+export default (): SiteConfig => ({
+  title: "My Blog",
+  // ... other config
 
-```ts
-import { SiteGenerator, loadConfig } from "bunki";
-const cfg = await loadConfig("./bunki.config.ts");
-const gen = new SiteGenerator({
-  contentDir: "content",
-  outputDir: "dist",
-  templatesDir: "templates",
-  config: cfg,
+  // Image upload configuration
+  s3: {
+    accessKeyId: process.env.S3_ACCESS_KEY_ID || "",
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY || "",
+    bucket: process.env.S3_BUCKET || "",
+    endpoint: process.env.S3_ENDPOINT, // Optional: for R2, etc.
+    region: process.env.S3_REGION || "auto",
+    publicUrl: process.env.S3_PUBLIC_URL || "",
+  },
 });
-await gen.initialize();
-await gen.generate();
 ```
 
-## CLI
+### Environment Variables
 
-```
-init | new | generate | serve | images:push | css
-```
+Set these in your `.env` file or export them in your shell:
 
-## Output
+```bash
+# Required
+export S3_ACCESS_KEY_ID="your-access-key"
+export S3_SECRET_ACCESS_KEY="your-secret-key"
+export S3_BUCKET="your-bucket-name"
+export S3_PUBLIC_URL="https://cdn.example.com"
 
-```
-- 📱 **Mobile-first** responsive templates
-  index.html
-  feed.xml
-  sitemap.xml
-  2025/... per-post dirs
-  tags/... tag pages
-  css/style.css (if enabled)
+# Optional (for Cloudflare R2 or custom endpoints)
+export S3_ENDPOINT="https://r2.cloudflarestorage.com"
+export S3_REGION="auto"
+
+# Optional (custom domain per bucket)
+export S3_CUSTOM_DOMAIN_YOUR_BUCKET="cdn.example.com"
 ```
 
-## Security
+### Basic Usage
 
-HTML sanitized; external links hardened; unsafe tags stripped.
+Upload all images:
 
-## Changelog
+```bash
+bunki images:push
+```
 
-v0.5.3 (current)
+This command:
 
-- Modularized CLI commands (init, new, generate, serve, css, images:push)
-- Dependency-injected command handlers for easier unit testing
-- Switched CLI entry to Bun.main/Bun.argv
-- Added/updated tests for init/new handlers; all suites green
-- Minor CSS command robustness and exit handling
+1. Scans the `images/` directory recursively
+2. Uploads all supported image formats
+3. Preserves the directory structure (year/slug/filename)
+4. Generates public URLs for each image
 
-v0.3.x
+### Command Options
 
-- PostCSS pipeline + `css` command
-- Export map + sideEffects=false for tree-shaking
-- Prepack build cleanup
+#### `--images <dir>`
 
-## Contribute
+Specify a custom images directory (default: `./images`)
 
 ```bash
-bun install
-bun run build
-bun test
+bunki images:push --images ./assets/images
 ```
 
-## License
+#### `--domain <domain>`
 
-MIT © KahWee Teng
+Set a custom domain for bucket identification (optional)
 
-- ⚡ **Simple CLI interface** with intuitive commands
+```bash
+bunki images:push --domain my-blog
+```
 
-## 🛠️ PostCSS Integration
+#### `--output-json <file>`
 
-Bunki v0.3.0+ includes built-in PostCSS processing, allowing you to use modern CSS frameworks like Tailwind CSS while keeping framework-specific dependencies in your project:
+Export a JSON mapping of filenames to their public URLs
 
-### CSS Configuration
+```bash
+bunki images:push --output-json image-urls.json
+```
 
-Configure CSS processing in your `bunki.config.ts`:
+This creates a JSON file with the structure:
 
-```typescript
-export default function (): SiteConfig {
-  return {
-    title: "My Blog",
-    description: "A blog built with Bunki",
-    baseUrl: "https://example.com",
-    domain: "blog",
-    // CSS processing configuration
-    css: {
-      input: "templates/styles/main.css", // Input CSS file
-      output: "css/style.css", // Output path in dist
-      postcssConfig: "postcss.config.js", // PostCSS config file
-      enabled: true, // Enable CSS processing
-      watch: false, // Watch for changes (dev mode)
-    },
-    // ... other config
-  };
+```json
+{
+  "2023/post-slug/image.jpg": "https://cdn.example.com/2023/post-slug/image.jpg",
+  "2024/travel/paris.jpg": "https://cdn.example.com/2024/travel/paris.jpg"
 }
 ```
 
-### CSS Processing Commands
+#### `--min-year <year>`
+
+Upload only images from the specified year onwards
 
 ```bash
-# Process CSS as part of site generation
-bunki generate
+# Upload only 2023 and 2024 images (skip 2021, 2022)
+bunki images:push --min-year 2023
 
-# Process CSS standalone
-bunki css
+# Upload only 2024 and newer images
+bunki images:push --min-year 2024
 
-# Watch CSS files for changes (development)
-bunki css --watch
+# Upload from 2022 onwards (all images in this example)
+bunki images:push --min-year 2022
 ```
 
-### Framework Integration Example (Tailwind CSS)
+This is useful for:
 
-1. **Install Tailwind in your project** (not in bunki):
+- Incremental uploads (upload only new images)
+- Testing uploads for specific years
+- Managing large image collections across multiple uploads
 
-```bash
-bun add -D tailwindcss @tailwindcss/postcss @tailwindcss/typography
-```
+### Complete Examples
 
-2. **Create `postcss.config.js`**:
+#### Cloudflare R2 Setup
 
-```javascript
-module.exports = {
-  plugins: [require("@tailwindcss/postcss")],
-};
-```
+1. **Create R2 bucket and API token** in Cloudflare dashboard
 
-3. **Create `tailwind.config.js`**:
+2. **Set environment variables:**
 
-```javascript
-module.exports = {
-  content: ["./content/**/*.{md,mdx}", "./templates/**/*.{njk,html}"],
-  theme: {
-    extend: {},
-  },
-  plugins: [require("@tailwindcss/typography")],
-};
+```bash
+export S3_ACCESS_KEY_ID="your-r2-api-token-id"
+export S3_SECRET_ACCESS_KEY="your-r2-api-token-secret"
+export S3_BUCKET="my-blog-images"
+export S3_ENDPOINT="https://r2.cloudflarestorage.com"
+export S3_REGION="auto"
+export S3_PUBLIC_URL="https://cdn.example.com"
 ```
 
-4. **Create your CSS file** (`templates/styles/main.css`):
+3. **Upload images:**
 
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+```bash
+bunki images:push --output-json image-urls.json
 ```
 
-Bunki will process your CSS through PostCSS and Tailwind, generating optimized output in your `dist` directory.
-
-## 📦 Installation
+#### AWS S3 Setup
 
-> **IMPORTANT**: Bunki requires Bun v1.2.21 or later as its runtime. It also works with Node.js v18+ but Bun is recommended for optimal performance.
+1. **Create S3 bucket and IAM user** in AWS Console
 
-### Prerequisites
+2. **Set environment variables:**
 
 ```bash
-# Install Bun if you don't have it
-curl -fsSL https://bun.sh/install | bash
-
-# Verify Bun version (should be 1.2.21 or later)
-bun --version
+export S3_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
+export S3_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+export S3_BUCKET="my-blog-bucket"
+export S3_REGION="us-east-1"
+export S3_PUBLIC_URL="https://my-blog-bucket.s3.amazonaws.com"
 ```
 
-### Installation Options
+3. **Upload images:**
 
 ```bash
-# Install globally with Bun
-bun install -g bunki
-
-# Or with npm
-npm install -g bunki
-
-# Or install locally in your project
-bun install bunki
-# or
-npm install bunki
-
-# Or from GitHub for development
-git clone git@github.com:kahwee/bunki.git
-cd bunki
-bun install
-bun run build
-bun link
+bunki images:push
 ```
 
-## 🚀 Quick Start
+#### Incremental Upload (Year-Based)
 
-### Initialize a New Site
+If you have thousands of images and want to upload them incrementally:
 
 ```bash
-# Create a new site with default templates and configuration
-bunki init
+# First, upload all 2023 images
+bunki images:push --min-year 2023 --max-year 2023
+
+# Next, upload 2024 images
+bunki images:push --min-year 2024 --max-year 2024
 
-# This creates:
-# - bunki.config.ts (configuration)
-# - content/ (for markdown posts)
-# - templates/ (Nunjucks templates)
-# - public/ (static assets)
+# Finally, upload 2025 images
+bunki images:push --min-year 2025
 ```
 
-### Add Content
+### Using Uploaded Images in Markdown
 
-Create markdown files in the `content` directory with frontmatter:
+After uploading, reference images in your Markdown posts:
 
-````markdown
+```markdown
 ---
-title: Your Post Title
-date: 2025-01-01T09:00:00-07:00
-tags: [web-development, javascript]
+title: "Paris Trip"
+date: 2024-06-15T10:00:00
+tags: [travel, france]
 ---
 
-# Your Post Title
+# My Trip to Paris
 
-Your post content goes here with **markdown** support!
+![Eiffel Tower at sunset](https://cdn.example.com/2024/paris-trip/eiffel-tower.jpg)
 
-```javascript
-console.log("Code highlighting works too!");
+![Louvre Museum](https://cdn.example.com/2024/paris-trip/louvre.jpg)
+
+## Evening Stroll
+
+The Parisian streets at night are magical.
+
+![Seine River at night](https://cdn.example.com/2024/paris-trip/seine-night.jpg)
 ```
 
-You can also embed videos using HTML5 video tags:
+### Using Uploaded Videos in Markdown
 
-<video src="https://example.com/video.mp4" controls width="640" height="360"></video>
+Upload MP4 videos alongside your images and embed them in your posts:
 
-Or with multiple formats for better browser compatibility:
+```markdown
+---
+title: "Travel Vlog"
+date: 2024-06-15T10:00:00
+tags: [travel, video]
+---
 
-<video controls width="640" height="360" poster="thumbnail.jpg">
-  <source src="video.mp4" type="video/mp4">
-  <source src="video.webm" type="video/webm">
-  Your browser does not support the video tag.
-</video>
-````
+# My Paris Adventure
 
-````
+Watch my trip to Paris:
 
-Or use the CLI to create a new post:
+<video controls width="640" height="360">
+  <source src="https://cdn.example.com/2024/paris-trip/travel-vlog.mp4" type="video/mp4">
+  Your browser does not support HTML5 video.
+</video>
 
-```bash
-bunki new "Your Post Title" --tags "web-development, javascript"
-````
+## Behind the Scenes
 
-### Generate Your Site
+Check out the making of the vlog:
 
-```bash
-# Generate the static site (includes CSS processing)
-bunki generate
+<video controls width="640" height="360">
+  <source src="https://cdn.example.com/2024/paris-trip/behind-scenes.mp4" type="video/mp4">
+  Your browser does not support HTML5 video.
+</video>
 ```
 
-### Preview Your Site
+**Video Upload Example:**
 
 ```bash
-# Start a local development server
-bunki serve
+# Upload all images and videos (including MP4 files)
+bunki images:push
 
-# Custom port
-bunki serve --port 3000
+# Upload only 2024 videos and images
+bunki images:push --min-year 2024
+
+# Preview what would be uploaded without actually uploading
+BUNKI_DRY_RUN=true bunki images:push --min-year 2024
 ```
 
-## ⚙️ Configuration
+**Video File Organization:**
 
-The `bunki.config.ts` file contains the configuration for your site:
+Keep videos organized the same way as images for consistency:
 
-```typescript
-import { SiteConfig } from "bunki";
-import { config } from "dotenv";
-
-// Load environment variables from .env file
-config();
-
-export default function (): SiteConfig {
-  return {
-    title: "My Blog",
-    description: "A blog built with Bunki",
-    baseUrl: "https://example.com",
-    domain: "blog",
-
-    // CSS processing configuration
-    css: {
-      input: "templates/styles/main.css",
-      output: "css/style.css",
-      postcssConfig: "postcss.config.js",
-      enabled: true,
-      watch: false,
-    },
-
-    // Cloud storage configuration for images
-    publicUrl: process.env.R2_PUBLIC_URL,
-    s3: {
-      accessKeyId: process.env.R2_ACCESS_KEY_ID || "",
-      secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || "",
-      bucket: process.env.R2_BUCKET || "",
-      endpoint: process.env.R2_ENDPOINT,
-      region: process.env.R2_REGION || "auto",
-    },
-  };
-}
+```
+images/
+├── 2024/
+│   └── travel-vlog/
+│       ├── intro.mp4
+│       ├── highlights.mp4
+│       ├── thumbnail.jpg
+│       └── poster.jpg
+└── 2025/
+    └── tutorial/
+        ├── part-1.mp4
+        ├── part-2.mp4
+        └── preview.jpg
 ```
 
-## 🖼️ Image Management
+**Video Tips:**
 
-Bunki uses Bun's native S3 API for efficient image uploads to S3-compatible services like Cloudflare R2.
+1. **File Size**: Keep MP4 files optimized (under 50MB recommended)
+   - Use tools like FFmpeg to compress before uploading
+   - Example: `ffmpeg -i input.mp4 -crf 28 output.mp4`
 
-### Environment Configuration
+2. **Format & Codec**:
+   - Use H.264 video codec for best compatibility
+   - Use AAC audio codec
+   - Container: MP4 (.mp4 extension)
 
-Create a `.env` file with your storage credentials:
+3. **Video Dimensions**:
+   - Keep 16:9 aspect ratio for web
+   - Common resolutions: 640x360, 1280x720, 1920x1080
 
-```env
-R2_ACCOUNT_ID=your-account-id
-R2_ACCESS_KEY_ID=your-access-key
-R2_SECRET_ACCESS_KEY=your-secret-key
-R2_BUCKET=your-bucket
-R2_PUBLIC_URL=https://your-cdn-url.com
-```
+4. **Hosting**:
+   - MP4s benefit from CDN caching via S3/R2
+   - Cloudflare R2 provides excellent video delivery
+   - AWS S3 with CloudFront for additional acceleration
+
+### Dry Run Mode
 
-For domain-specific custom domains:
+Test the upload process without actually uploading:
 
-```env
-R2_CUSTOM_DOMAIN_EXAMPLE_COM=cdn.example.com
+```bash
+# Preview what would be uploaded (no actual upload)
+BUNKI_DRY_RUN=true bunki images:push
 ```
 
-### Upload Commands
+This shows:
 
-```bash
-# Upload all images from the images/ directory
-bunki images:push
+- Which images would be uploaded
+- The directory structure that would be created
+- Generated public URLs
 
-# Specify a different images directory
-bunki images:push --images path/to/images
+### Troubleshooting
 
-# Output URL mapping to a JSON file for reference
-bunki images:push --output-json image-urls.json
+#### "Missing S3 configuration"
 
-# Upload for a specific domain
-bunki images:push --domain example.com
-```
-
-Supported formats: **JPG**, **PNG**, **GIF**, **WebP**, **SVG**
-
-## 📁 Directory Structure
-
-```
-my-blog/
-├── bunki.config.ts         # Site configuration
-├── postcss.config.js       # PostCSS configuration (optional)
-├── tailwind.config.js      # Tailwind config (if using Tailwind)
-├── .env                    # Environment variables
-├── content/                # Markdown content
-│   └── 2025/               # Year-based organization
-│       ├── my-first-post.md
-│       └── another-post.md
-├── templates/              # Nunjucks templates
-│   ├── base.njk           # Base layout
-│   ├── index.njk          # Homepage
-│   ├── post.njk           # Post template
-│   ├── tag.njk            # Tag page
-│   ├── tags.njk           # Tags index
-│   ├── archive.njk        # Year archive
-│   └── styles/            # CSS source files
-│       └── main.css       # Main stylesheet
-├── images/                 # Local images (uploaded to cloud)
-├── public/                # Static assets (copied to dist)
-├── src/                   # Tag descriptions
-│   └── tags.toml          # Tag metadata
-└── dist/                  # Generated site (output)
-    ├── index.html
-    ├── css/
-    │   └── style.css      # Processed CSS
-    ├── 2025/
-    │   └── my-first-post/
-    │       └── index.html
-    ├── tags/
-    ├── feed.xml           # RSS feed
-    └── sitemap.xml        # Sitemap
-```
-
-## 🚨 CLI Commands
+Ensure all required environment variables are set. Check `bunki.config.ts` and your `.env` file.
 
-```bash
-Usage: bunki [options] [command]
+#### "No image files found"
 
-Commands:
-  init [options]            Initialize a new site with templates
-  new [options] <title>     Create a new blog post
-  generate [options]        Generate static site from content
-  css [options]             Process CSS using PostCSS
-  serve [options]           Start local development server
-  images:push [options]     Upload images to cloud storage
-  help [command]            Display help for command
+- Verify images exist in `images/` directory
+- Check that files have supported extensions (.jpg, .png, .gif, .webp, .svg)
+- Ensure the directory structure is correct (e.g., `images/2024/post-slug/image.jpg`)
 
-Options:
-  -V, --version            Display version number
-  -h, --help               Display help for command
-```
+#### "Unauthorized" or "Access Denied"
 
-### Detailed Command Options
+- Verify S3 credentials (access key and secret key)
+- Check that the IAM user/API token has S3 permissions
+- Confirm the bucket name is correct
 
-```bash
-# Initialize new site
-bunki init --config custom.config.ts
+#### "Invalid bucket name"
 
-# Create new post
-bunki new "My Post Title" --tags "javascript, web-dev"
+- S3 bucket names must be globally unique
+- Use only lowercase letters, numbers, and hyphens
+- Bucket names must be 3-63 characters long
 
-# Generate with custom options
-bunki generate --config bunki.config.ts --output dist
+### Advanced Configuration
 
-# CSS processing
-bunki css --watch              # Watch for changes
-bunki css --output dist        # Custom output directory
+#### Custom Domain per Bucket
 
-# Development server
-bunki serve --port 3000        # Custom port
-bunki serve --output dist      # Serve from custom directory
+If you have multiple S3 buckets with different custom domains:
 
-# Image upload
-bunki images:push --domain example.com
-bunki images:push --images custom/path --output-json mapping.json
+```bash
+export S3_CUSTOM_DOMAIN_MY_BUCKET="cdn1.example.com"
+export S3_CUSTOM_DOMAIN_BACKUP_BUCKET="cdn2.example.com"
 ```
 
-## 🏗️ Development
+The bucket name is converted to uppercase and hyphens to underscores for the environment variable name.
 
-### Prerequisites for Contributors
+#### Direct CDN URLs
 
-```bash
-git clone git@github.com:kahwee/bunki.git
-cd bunki
-bun install
+Configure public URLs with custom domains:
+
+```typescript
+// bunki.config.ts
+s3: {
+  // ... other config
+  publicUrl: "https://img.example.com",
+}
 ```
 
-### Development Commands
+Or via environment variable:
 
 ```bash
-# Build the project
-bun run build
+export S3_PUBLIC_URL="https://img.example.com"
+```
+
+### Performance Tips
 
-# Run in development mode with watch
-bun run dev
+1. **Use year-based filtering** for large image collections:
 
-# Run tests
-bun test
+   ```bash
+   bunki images:push --min-year 2024  # Only newest images
+   ```
 
-# Run tests with coverage
-bun test:coverage
+2. **Organize by post slug** for better directory structure:
 
-# Watch tests
-bun test:watch
+   ```
+   images/2024/post-title/image.jpg
+   images/2024/post-title/photo.jpg
+   ```
 
-# Type checking
-bun run typecheck
+3. **Compress images before uploading** to save storage:
+   - Use tools like `imagemin` or built-in OS utilities
+   - Aim for 500KB or smaller per image
+
+4. **Use modern formats** (WebP) for better compression:
+   - JPG/PNG for screenshots
+   - WebP for photos
+   - SVG for icons/graphics
+
+## CLI Commands
+
+```bash
+bunki init [--config FILE]                 # Initialize new site
+bunki new <TITLE> [--tags TAG1,TAG2]       # Create new post
+bunki generate [--config FILE]             # Build static site
+bunki serve [--port 3000]                  # Start dev server
+bunki css [--watch]                        # Process CSS
+bunki images:push [--domain DOMAIN]        # Upload images to cloud
+```
+
+## Output Structure
+
+```
+dist/
+├── index.html              # Homepage
+├── feed.xml                # RSS feed
+├── sitemap.xml             # XML sitemap
+├── css/style.css           # Processed stylesheet
+├── 2025/
+│   └── my-post/
+│       └── index.html      # Post page
+├── tags/
+│   └── web/
+│       └── index.html      # Tag page
+└── page/
+    └── 2/index.html        # Paginated content
+```
+
+## Features
+
+- **Markdown Processing**: Frontmatter extraction, code highlighting, HTML sanitization
+- **Security**: XSS protection, sanitized HTML, link hardening
+- **Performance**: Static files, optional gzip, optimized output
+- **Templating**: Nunjucks with custom filters and macros
+- **Styling**: Built-in PostCSS support for modern CSS frameworks
+- **Media Management**: Direct S3/R2 uploads for images and MP4 videos with URL mapping
+- **Incremental Uploads**: Year-based filtering (`--min-year`) for large media collections
+- **SEO**: Automatic RSS feeds, sitemaps, meta tags
+- **Pagination**: Configurable posts per page
+- **Archives**: Year-based and tag-based organization
+
+## Development
 
-# Format code
-bun run format
+```bash
+git clone git@github.com:kahwee/bunki.git
+cd bunki
+bun install
 
-# Clean build artifacts
-bun run clean
+bun run build              # Build distribution
+bun test                   # Run test suite
+bun test:coverage          # Test coverage report
+bun run typecheck          # TypeScript validation
+bun run format             # Prettier formatting
 ```
 
-### Project Structure
+## Project Structure
 
 ```
 bunki/
 ├── src/
-│   ├── cli.ts              # CLI interface
-│   ├── config.ts           # Configuration management
-│   ├── site-generator.ts   # Core site generation
-│   ├── server.ts           # Development server
-│   ├── parser.ts           # Markdown parsing
-│   ├── types.ts            # TypeScript types
-│   └── utils/
-│       ├── css-processor.ts    # PostCSS integration
-│       ├── file-utils.ts       # File operations
-│       ├── image-uploader.ts   # Image cloud upload
-│       ├── markdown-utils.ts   # Markdown processing
-│       └── s3-uploader.ts      # S3 API client
-├── test/                   # Test files
-├── fixtures/               # Test fixtures
-└── dist/                   # Built output
+│   ├── cli.ts             # CLI interface
+│   ├── config.ts          # Configuration management
+│   ├── site-generator.ts  # Core generation logic
+│   ├── server.ts          # Development server
+│   ├── parser.ts          # Markdown parsing
+│   ├── types.ts           # TypeScript types
+│   └── utils/             # Utility modules
+├── test/                  # Test suite (mirrors src/)
+├── templates/             # Example templates
+├── fixtures/              # Test fixtures
+└── dist/                  # Built output
 ```
 
-## 📋 Changelog
+## Changelog
 
-### v0.3.0 (Latest)
+### v0.7.0 (Current)
 
-- ✨ **NEW**: PostCSS integration with configurable CSS processing
-- ✨ **NEW**: CSS watch mode for development
-- ✨ **NEW**: Framework-agnostic CSS support (Tailwind, etc.)
-- 🔄 **IMPROVED**: Enhanced CLI with `css` command
-- 🔄 **IMPROVED**: Better error handling and fallbacks
-- 🐛 **FIXED**: Directory existence validation for development server
-- 📚 **DOCS**: Comprehensive PostCSS integration guide
+- **Media uploads**: Added MP4 video support alongside image uploads
+- **Incremental uploads**: Year-based filtering with `--min-year` option
+- **Enhanced documentation**: Comprehensive video upload guide with examples
+- **Test coverage**: Added 10+ tests for image/video uploader functionality
+- **Fixed timestamps**: Stable dates in test fixtures to prevent flipping
 
-### v0.2.6
+### v0.6.1
 
-- 🐛 **FIXED**: Server directory existence check
-- 🔄 **IMPROVED**: Error handling and logging
-- 📚 **DOCS**: Enhanced documentation
+- Version bump and welcome date stabilization
+- Test formatting improvements
+- Code style consistency updates
 
-## 🤝 Contributing
+### v0.5.3
 
-Contributions are welcome! Please read our contributing guidelines and feel free to submit issues and pull requests.
+- Modularized CLI commands with dependency injection
+- Enhanced test coverage (130+ tests, 539+ assertions)
+- Fixed CLI entry point detection (Bun.main compatibility)
+- Added comprehensive server tests using Bun.serve()
+- Improved CSS processor with fallback support
 
-### Areas for Contribution
+### v0.3.0
 
-- 🐛 Bug fixes and improvements
-- 📝 Documentation improvements
-- 🧪 Additional test coverage
-- ✨ New features (CSS plugins, template engines, etc.)
-- 🎨 Template improvements
+- PostCSS integration with CSS processing command
+- Framework-agnostic CSS support (Tailwind, etc.)
+- CSS watch mode for development
+- Better error handling and recovery
 
-## 📄 License
+## Contributing
 
-MIT © [KahWee Teng](https://github.com/kahwee)
+Contributions welcome! Areas for improvement:
 
----
+- Bug fixes and error handling
+- Documentation and examples
+- Test coverage expansion
+- Performance optimizations
+- New features and plugins
 
-## 🙋‍♂️ Support
+## License
 
-- 📚 [Documentation](https://github.com/kahwee/bunki)
-- 🐛 [Issues](https://github.com/kahwee/bunki/issues)
-- 💬 [Discussions](https://github.com/kahwee/bunki/discussions)
+MIT © [KahWee Teng](https://github.com/kahwee)
 
-Built with ❤️ using [Bun](https://bun.sh)
+Built with [Bun](https://bun.sh)