# Workflow: Create a Page

This workflow guides you through creating a new page in the CMS.

## Prerequisites

- SDK CLI installed (`@riverbankcms/sdk`)
- Environment variables configured in `.env.local`
- Latest content pulled: `riverbankcms pull`

## Steps

### 1. Create the Page

```bash
riverbankcms page upsert <identifier> \
  --title "Page Title" \
  --path /url-path \
  --seo-title "SEO Title" \
  --seo-description "Meta description for search engines"
```

**Example:**

```bash
riverbankcms page upsert contact \
  --title "Contact Us" \
  --path /contact \
  --seo-title "Contact Us | Company Name" \
  --seo-description "Get in touch with our team. We'd love to hear from you."
```

### 2. Add Blocks to the Page

Add a hero block:

```bash
riverbankcms block upsert contact hero-section \
  --kind block.hero \
  --data '{"heading": "Contact Us", "subheading": "We would love to hear from you"}'
```

Add a body text block:

```bash
riverbankcms block upsert contact intro-text \
  --kind block.body-text \
  --data '{"content": "<p>Reach out using the form below or email us directly.</p>"}'
```

Add more blocks as needed. See `block-types.md` for available block types.

### 3. Preview Blocks (Optional)

Preview individual blocks before publishing:

```bash
riverbankcms preview block.hero \
  --data '{"heading": "Contact Us", "subheading": "We would love to hear from you"}' \
  --open
```

### 4. Verify the Page

Check the page was created:

```bash
riverbankcms page get contact
```

List blocks on the page:

```bash
riverbankcms block list contact
```

### 5. Publish the Page

When ready to make the page live:

```bash
riverbankcms page publish contact
```

## Additional Operations

### Reordering Blocks

Change the order of blocks on the page:

```bash
riverbankcms block reorder contact hero-section intro-text form-section
```

Blocks will appear in the order specified.

### Editing Block Content

Update an existing block by upserting with new data:

```bash
riverbankcms block upsert contact hero-section \
  --kind block.hero \
  --data '{"heading": "New Heading", "subheading": "Updated subheading"}'
```

### Deleting Blocks

Remove a block from the page:

```bash
riverbankcms delete block contact hero-section --yes
```

### Using JSON Files for Complex Content

For blocks with complex nested content, use a JSON file:

**hero-content.json:**

```json
{
  "heading": "Contact Our Team",
  "subheading": "We're here to help",
  "backgroundImage": {
    "src": "/images/contact-bg.jpg",
    "alt": "Office background"
  },
  "cta": {
    "text": "Send Message",
    "url": "#contact-form"
  }
}
```

```bash
riverbankcms block upsert contact hero-section \
  --kind block.hero \
  --file ./hero-content.json
```

## Complete Example

Create a full about page with multiple blocks:

```bash
# 1. Create the page
riverbankcms page upsert about \
  --title "About Us" \
  --path /about \
  --seo-title "About Us | Company Name" \
  --seo-description "Learn about our company, mission, and team."

# 2. Add hero block
riverbankcms block upsert about hero \
  --kind block.hero \
  --data '{"heading": "About Us", "subheading": "Our story and mission"}'

# 3. Add introduction text
riverbankcms block upsert about intro \
  --kind block.body-text \
  --data '{"content": "<p>Founded in 2020, we have been...</p>"}'

# 4. Add team section (if using a team block)
riverbankcms block upsert about team \
  --kind block.body-text \
  --data '{"content": "<h2>Our Team</h2><p>Meet the people behind the company.</p>"}'

# 5. Verify
riverbankcms page get about
riverbankcms block list about

# 6. Publish when ready
riverbankcms page publish about
```

## Troubleshooting

### Page already exists

If the page identifier already exists, `upsert` will update it. This is intentional - use unique identifiers for new pages.

### Block not appearing

- Verify the block was created: `riverbankcms block get <page> <block-id>`
- Check block kind is valid: see `block-types.md`
- Ensure JSON data is properly formatted

### Page not showing on site

- Check if page is published: `riverbankcms page get <identifier>`
- Look for `status: "published"` in the output
- Publish if needed: `riverbankcms page publish <identifier>`

## Related Workflows

- **Add a Block** - Add blocks to existing pages: see `add-block.md`
- **Block Extensions** - Add layout variants to system blocks: see `block-extensions.md`
- **Custom Blocks** - Create site-specific blocks: see `custom-block.md`
- **Content Types** - Create structured content with pages: see `content-types.md`
- **CMS-ify a Page** - Convert hard-coded pages to CMS-driven: see `cmsify-page.md`
- **Publish Workflow** - Publishing content safely: see `publish-workflow.md`
