# 📝 Suno Share Site

A static site for sharing Claude Code conversations and prompts from the Suno engineering team. Built with Astro, this site allows you to export Claude Code sessions and publish them as searchable, shareable content.

---

## 🌟 Features

- 🤖 **Claude Code Integration**: Export conversations directly from Claude Code sessions
- 🔍 **Full-Text Search**: Fast, keyboard-accessible search across all prompts
- 🎨 **Dark/Light Theme**: Automatic theme switching with manual override
- 📱 **Responsive Design**: Mobile-first, works on all devices
- 📝 **MDX Support**: Rich formatting with code blocks, syntax highlighting, and diff support
- 🚀 **Vercel Deployment**: Built-in deployment scripts
- ⚡ **Static Generation**: Fast loading with Astro's static site generation

---

## 📁 Project Structure

```
share-site/
├── scripts/               # Python utilities for exporting conversations
│   ├── export-claude-chat.py       # Main export script
│   ├── convert-claude-chat.py      # Convert JSONL to MDX
│   ├── list-sessions.py            # List available sessions
│   └── deploy-to-vercel.py         # Deploy to Vercel
├── src/
│   ├── app/              # Layouts, styles, config
│   ├── components/       # UI components
│   │   ├── prompts/      # Prompt-specific components
│   │   ├── search/       # Search functionality
│   │   └── ui/           # MDX components
│   ├── content/
│   │   └── prompts/      # Published conversations (MDX files)
│   └── pages/            # Routes (/, /prompts, /prompts/[slug])
└── public/               # Static assets
```

---

## 🚀 Quick Start

### Prerequisites

Before using the share-prompt workflow, you need to:

1. **Install Vercel CLI** (if you want to use the `/share-prompt` command):
   ```bash
   cd share-site
   pnpm install
   ```

2. **Link to Vercel Project**:
   ```bash
   cd share-site
   pnpm vercel link
   ```
   - Select your team (e.g., "Suno")
   - Select or confirm the project name (e.g., "share")
   - This creates a `.vercel` directory with your project configuration

3. **Authenticate with Vercel** (first time only):
   ```bash
   pnpm vercel login
   ```

Once set up, the `.vercel/project.json` file will contain your project and organization IDs, enabling the deployment scripts to work properly.

### Installation

```bash
# From the monorepo root
pnpm install

# Or from share-site directory
cd share-site
pnpm install
```

### Development

```bash
# Start dev server
pnpm dev

# Visit http://localhost:4321
```

### Build

```bash
# Build for production
pnpm build

# Preview production build
pnpm preview
```

---

## 📤 Exporting Claude Code Conversations

### Option 0: Using the `/share-prompt` Command (Easiest!)

The fastest way to share a conversation is using the `/share-prompt` Claude Code command:

1. **In your Claude Code conversation**, type:
   ```
   /share-prompt
   ```

2. **Follow the prompts**:
   - Confirm which session to export (defaults to current)
   - Provide a title for the conversation
   - The command will automatically export and deploy to Vercel

3. **Get your shareable link** instantly!

**Requirements**:
- Vercel must be set up (see [First-Time Setup](#first-time-setup) below)
- `.vercel/project.json` must exist in `share-site/`

### Option 1: Export Latest Session

```bash
cd scripts

# Export the most recent Claude Code session
python export-claude-chat.py $(ls -t ~/.claude/projects/*/*.jsonl | head -n 1) \
  --title "My Conversation Title" \
  --output ../src/content/prompts/my-conversation.mdx
```

### Option 2: List and Choose Session

```bash
cd scripts

# List all available sessions
python list-sessions.py

# Export a specific session
python export-claude-chat.py ~/.claude/projects/my-project/session_123.jsonl \
  --title "Building a Feature" \
  --output ../src/content/prompts/building-feature.mdx
```

### Option 3: Export and Deploy

```bash
# Export and immediately deploy to Vercel
python export-claude-chat.py session.jsonl \
  --title "My Conversation" \
  --output ../src/content/prompts/my-convo.mdx \
  --deploy
```

### Export Script Options

- `--title, -t`: Set the conversation title
- `--output, -o`: Specify output file path (default: stdout)
- `--deploy, -d`: Automatically deploy to Vercel after export

---

## ✍️ Manual Content Creation

You can also manually create prompt files in `src/content/prompts/`:

```mdx
---
title: "My Conversation Title"
desc: "A brief description of what this conversation covers"
date: 2025-10-21
slug: "my-conversation-slug"
tags: ["feature-development", "debugging", "api"]
category: "prompt"
sessionId: "session_abc123"  # optional
repository: "glockenspiel"    # optional
branch: "main"                # optional
isDraft: false
---

# Conversation Content

Your conversation content in markdown/MDX format goes here...

## Code Examples

\`\`\`typescript
// Your code here
\`\`\`
```

---

## 🎨 Customization

### Site Configuration

Edit site metadata in `src/app/config/site.ts`:

```typescript
export const siteConfig = {
  title: 'Your Site Title',
  siteUrl: 'https://your-site.com',
  description: 'Your site description',
  navigation: [
    { name: 'Home', path: '/' },
    { name: 'Prompts', path: '/prompts' },
  ],
  social: {
    github: 'https://github.com/your-org',
    twitter: 'https://twitter.com/your-handle',
  },
  // ... more config
};
```

### Styling

- Global styles: `src/app/styles/global.css`
- CSS variables: `src/app/styles/variables.css`
- Components: Individual `.astro` files have scoped styles

---

## 🔍 Search

The site includes full-text search powered by a client-side search component:

- **Keyboard shortcut**: `Cmd/Ctrl + K`
- **Searches**: Titles, descriptions, tags, and content
- **Fuzzy matching**: Finds results even with typos

Search configuration: `src/components/search/`

---

## 🚢 Deployment

### Vercel (Recommended)

#### First-Time Setup

1. **Install dependencies** (includes Vercel CLI):
   ```bash
   cd share-site
   pnpm install
   ```

2. **Authenticate with Vercel**:
   ```bash
   pnpm vercel login
   ```
   - Follow the prompts to authenticate via browser
   - This creates a token in `~/.vercel` for future deployments

3. **Link to Vercel project**:
   ```bash
   pnpm vercel link
   ```
   - Select your team (e.g., "Suno")
   - Select or create the project (e.g., "share")
   - This creates `.vercel/project.json` with your project configuration
   - The project ID and org ID are required for deployments

4. **Verify setup**:
   ```bash
   cat .vercel/project.json
   ```
   - Should show `projectId` and `orgId`

#### Deploying

```bash
# Option 1: Deploy via Python script (used by /share-prompt command)
cd scripts
python deploy-to-vercel.py

# Option 2: Deploy via Vercel CLI directly
cd share-site
pnpm vercel deploy  # Preview deployment

```

#### Troubleshooting Deployment

- **Error: "Project not found"**: Run `pnpm vercel link` to connect to your Vercel project
- **Error: "Not authenticated"**: Run `pnpm vercel login` to authenticate
- **Missing `.vercel` directory**: This is created by `vercel link` and contains project configuration
- **Command not found**: Make sure you're using `pnpm vercel`, not just `vercel` (uses local CLI)

### Other Platforms

The site generates static output in `dist/` which can be deployed to:

- Netlify
- Cloudflare Pages
- AWS S3 + CloudFront
- Any static hosting service

---

## 🛠️ Available Scripts

```bash
# Development
pnpm dev                 # Start dev server
pnpm start               # Alias for dev

# Build
pnpm build               # Build for production
pnpm preview             # Preview production build

# Code Quality
pnpm lint                # Run ESLint
pnpm lint:fix            # Fix ESLint issues
pnpm prettier            # Format code
pnpm prettier:check      # Check formatting
pnpm type-check          # TypeScript type checking

# Maintenance
pnpm clean               # Clean build artifacts
pnpm dev:clean           # Clean and reinstall
```

---

## 📦 Python Scripts

### `export-claude-chat.py`
Main export script that combines conversion and deployment.

### `convert-claude-chat.py`
Converts Claude Code JSONL format to MDX with frontmatter.

### `list-sessions.py`
Lists all available Claude Code sessions with metadata.

### `deploy-to-vercel.py`
Builds and deploys the site to Vercel.

---

## 🔧 Content Schema

Prompts use this schema (defined in `src/content.config.ts`):

```typescript
{
  title: string;              // Required
  desc: string;               // Max 200 chars
  date: Date;                 // Publication date
  slug: string;               // URL slug
  tags: string[];             // Array of tags
  category: string;           // Default: "prompt"
  sessionId?: string;         // Optional Claude session ID
  repository?: string;        // Optional repo name
  branch?: string;            // Optional branch name
  isDraft?: boolean;          // Hide from listing
}
```

---

## 🎯 Workflow Example

1. **Have a conversation in Claude Code**
2. **Export the session**:
   ```bash
   cd share-site/scripts
   python export-claude-chat.py $(ls -t ~/.claude/projects/*/*.jsonl | head -n 1) \
     --title "Implementing Search Feature" \
     --output ../src/content/prompts/search-feature.mdx
   ```
3. **Review the exported MDX file**
4. **Build and preview locally**:
   ```bash
   cd ..
   pnpm build
   pnpm preview
   ```
5. **Deploy**:
   ```bash
   cd scripts
   python deploy-to-vercel.py
   ```

---

## 🐛 Troubleshooting

### Build Warnings

If you see warnings about missing collections (posts, howtos, etc.), these are expected as the template was cleaned up. They won't affect functionality.

### Search Not Working

Ensure JavaScript is enabled and check browser console for errors. The search component requires client-side JavaScript.

### Styles Not Loading

Run `pnpm dev:clean` to clear cache and rebuild.

---

## 📄 License

MIT

---

## 🙋 Support

For issues or questions:
- File an issue in the repository
- Check existing documentation in the scripts
- Review the Astro documentation: https://docs.astro.build