Page Structure Guide

This page serves as a comprehensive reference for content developers on how to properly structure pages with correct frontmatter. Understanding these patterns will help avoid common issues like duplicate titles and ensure consistent formatting across the site.

Page Structure Basics

Every content page in this site follows a consistent structure with three main parts:

1. Frontmatter - YAML metadata at the top of the file
2. Content - The actual page content in Markdown
3. Components - Astro components for enhanced functionality

Frontmatter Structure

Required Frontmatter Fields

Every page must include these essential fields:

---
title: "Page Title"
description: "Brief description of the page content"
roles: ["Guest"]  # or ["Member"], ["CoreTeam"], ["Admin"]
---

Optional but Recommended Fields

---
title: "Page Title"
description: "Brief description of the page content"
roles: ["CoreTeam"]
tags: ["sales", "training", "objections"]
status: "published"  # published, draft, review, archived
lastUpdated: 2024-11-06  # YYYY-MM-DD format
sidebar:
  label: "Custom Sidebar Label"
  order: 1
---

Role-Based Access Control

The roles field determines who can access the content:

• ["Guest"] - Accessible to everyone (public content)
• ["Member"] - Members and above only
• ["CoreTeam"] - Core Team and Admin only
• ["Admin"] - Admins only
• ["Member", "CoreTeam", "Admin"] - Multiple role levels

Role Hierarchy

Admin (Level 4) → CoreTeam (Level 3) → Member (Level 2) → Guest (Level 1)

Content Structure Guidelines

CRITICAL: Avoid Duplicate Titles

❌ WRONG - This creates duplicate titles:

---
title: "Welcome Page"
description: "Welcome to our platform"
roles: ["Guest"]
---

# Welcome Page

This content will show the title twice!

✅ CORRECT - No H1 heading needed:

---
title: "Welcome Page"
description: "Welcome to our platform"
roles: ["Guest"]
---

Welcome to our platform! This is the correct way to structure content.

Heading Hierarchy

Start your content with H2 headings (##) since Starlight uses the frontmatter title as the main H1:

---
title: "Sales Training"
description: "Complete sales training program"
roles: ["CoreTeam"]
---

## Module 1: Introduction

This is the first section of our training.

### Key Concepts

Important points to remember.

#### Sub-concept

Detailed explanation here.

Complete Page Examples

1. Basic Public Page

---
title: "About Us"
description: "Learn about our team and mission"
roles: ["Guest"]
tags: ["about", "company"]
status: "published"
---

Welcome to our team platform! This section provides information about who we are and what we do.

## Our Mission

We are dedicated to...

## Team Values

- Integrity
- Excellence
- Collaboration

2. Core Team Training Page

---
title: "Overcoming Price Objections"
description: "Strategies for handling price-related objections effectively"
roles: ["CoreTeam"]
tags: ["sales", "objections", "pricing", "training"]
status: "published"
lastUpdated: 2024-11-06
sidebar:
  label: "Price Objections"
  order: 3
---

## Understanding Price Objections

Price objections are one of the most common challenges in sales. This training will help you handle them effectively.

## Common Price Objection Scenarios

### "That's too expensive"
<VideoPlayer
  videoLibraryId="123456"
  videoId="price-objection-1"
  title="Handling 'Too Expensive' Responses"
  description="Techniques for addressing price concerns"
  duration="12:30"
/>

### "I can get it cheaper elsewhere"
<VideoPlayer
  videoLibraryId="123456"
  videoId="price-objection-2"
  title="Competitive Price Responses"
  description="How to position against competitors"
  duration="15:45"
/>

## Key Takeaways

- Focus on value, not price
- Understand the underlying concern
- Build ROI justification

3. Video Series Page with Playlist

---
title: "Complete Objection Handling Series"
description: "Comprehensive video series for handling all types of sales objections"
roles: ["CoreTeam"]
tags: ["sales", "objections", "video-series", "training"]
status: "published"
lastUpdated: 2024-11-06
sidebar:
  label: "Objection Series"
  order: 1
---

## Mastering Objection Handling

This complete video series covers all major objection types and proven response strategies.

## Video Training Series

<VideoPlaylist
  videos={[
    {
      videoLibraryId: "123456",
      videoId: "objection-overview",
      title: "Objection Handling Overview",
      description: "Introduction to the objection handling framework",
      duration: "20:15"
    },
    {
      videoLibraryId: "123456",
      videoId: "price-objections",
      title: "Price Objections",
      description: "Handling concerns about cost and value",
      duration: "18:30"
    },
    {
      videoLibraryId: "123456",
      videoId: "timing-objections",
      title: "Timing Objections",
      description: "Dealing with 'not right now' responses",
      duration: "16:45"
    }
  ]}
  defaultVideo="objection-overview"
  showPlaylist={true}
/>

## Implementation Checklist

After watching the series, ensure you can:

- [ ] Identify the real concern behind objections
- [ ] Apply the appropriate response framework
- [ ] Practice with role-play scenarios
- [ ] Document successful objection responses

4. Admin Resource Page

---
title: "System Administration Guide"
description: "Administrative procedures and system management"
roles: ["Admin"]
tags: ["admin", "system", "procedures"]
status: "published"
lastUpdated: 2024-11-06
sidebar:
  label: "Admin Guide"
  order: 1
---

## System Administration Overview

This guide contains administrative procedures for managing the team platform.

## User Management

### Adding New Members

<VideoPlayer
  videoLibraryId="123456"
  videoId="admin-add-user"
  title="Adding New Team Members"
  description="Step-by-step process for user onboarding"
  duration="8:20"
  showSpeed={true}
  rememberPosition={true}
/>

### Managing Permissions

Detailed procedures for managing user roles and access permissions.

## System Maintenance

Regular maintenance tasks and troubleshooting procedures.

## Quick Reference

| Task | Video | Duration |
|------|-------|----------|
| Add User | admin-add-user | 8:20 |
| Reset Password | admin-reset-pw | 5:15 |
| Update Roles | admin-roles | 12:30 |

Best Practices Summary

1. Frontmatter

• Always include title, description, and roles
• Use descriptive titles (no duplicate H1 headings in content)
• Set appropriate access levels

2. Content Structure

• Start with H2 headings (##) since title is already H1
• Use logical heading hierarchy
• Combine text with multimedia appropriately

3. Video Integration

• Use VideoPlayer for single videos
• Use VideoPlaylist for video series
• Include duration and descriptions for better UX

4. Organization

• Use tags for categorization
• Set sidebar order for logical navigation
• Keep lastUpdated current

5. File Naming

• Use kebab-case for file names: price-objections.md
• Place files in appropriate role-based directories
• Keep names descriptive and concise

Common Mistakes to Avoid

1. Duplicate Titles - Don’t add H1 headings when frontmatter has title
2. Wrong Role Levels - Set appropriate access permissions
3. Missing Descriptions - Always include helpful descriptions
4. Inconsistent Formatting - Follow the established patterns
5. Poor File Organization - Use the correct directory structure

Directory Structure Reference

src/content/docs/
├── public/
│   ├── About/
│   ├── Policies/
│   └── contact.md
├── protected/
│   ├── member/
│   │   └── [member-accessible content]
│   ├── coreteam/
│   │   ├── objections/
│   │   ├── prospecting/
│   │   ├── presentations/
│   │   └── [core-team content]
│   └── admin/
│       ├── video-template.md
│       ├── page-structure-guide.md
│       └── [admin-only content]

Use this guide as your reference when creating new content pages to ensure consistency and avoid common structural issues.