Creating Pages

Creating Pages

This guide explains the complete frontmatter requirements for creating pages in this Team 8531 documentation site.

Project Architecture

This project uses Astro with Starlight framework for documentation, featuring:

• Role-based access control
• Content lifecycle management
• Built-in search functionality
• Sidebar navigation control

Required Frontmatter Fields

Every page must include these three required fields:

---
title: "Page Title"                    # Displayed in browser tab and main heading
description: "Brief description"       # SEO and preview text
roles: ["Guest"]                       # Array of allowed roles
---

1. Title

• Required: The page title
• Displayed in:
  • Browser tab
  • Main page heading (H1)
  • Sidebar navigation (unless overridden)
• Should be concise but descriptive

2. Description

• Required: Brief summary of the page content
• Used for:
  • SEO meta description
  • Search result previews
  • Social media sharing
• Keep under 160 characters for optimal SEO

3. Roles

• Required: Array determining who can access the content
• Accepts any combination of:
  • "Guest": Publicly accessible content
  • "Member": Requires login
  • "CoreTeam": Leadership team only
  • "Admin": Administrators only

Example:

roles: ["Member", "CoreTeam", "Admin"]  # Multiple roles
roles: ["Guest"]  # Public content
roles: ["Admin"]  # Admin-only content

Optional Frontmatter Fields

Content Management Fields

Status

Controls the content lifecycle state:

status: "published"  # Default
# Options: "published", "draft", "review", "archived"

• published: Visible in navigation and search
• draft: Hidden from navigation, accessible via direct URL
• review: Under review for publication
• archived: No longer maintained content

Tags

Array of strings for categorization and search:

tags: ["documentation", "guide", "tutorial", "admin"]

Last Updated

Timestamp for tracking content freshness:

lastUpdated: 2024-12-11T00:00:00.000Z  # ISO 8601 format

Search Control

Control page inclusion in search results:

pagefind: false  # Exclude from search (default: true)

Sidebar Navigation

Customize how the page appears in the sidebar:

sidebar:
  label: "Custom Display Name"  # Override title in navigation
  order: 10  # Sort order (lower = higher priority)
  badge:  # Optional badge
    text: "New"
    variant: "tip"  # Options: "note", "tip", "caution", "danger"

Archived Content Metadata

When using status: "archived", you can add:

status: "archived"
archiveDate: "2024-01-15"  # When it was archived
archivedReason: "Replaced by new system"  # Why it was archived

File Types and Extensions

Markdown (.md)

• Use for simple text content
• Supports standard Markdown features
• Cannot use interactive components

MDX (.mdx)

• Use for interactive content with React components
• Supports all Markdown features plus:
  • Google Drive embeddings
  • Video players
  • Interactive diagrams
  • Custom React components

Directory Structure

Content location determines default access level:

src/content/docs/
├── public/                    # Guest content
│   └── *.md, *.mdx
├── protected/
│   ├── member/               # Member content
│   │   └── *.md, *.mdx
│   ├── coreteam/             # CoreTeam content
│   │   └── *.md, *.mdx
│   └── admin/                # Admin content
│       └── *.md, *.mdx

Complete Examples

Minimal Public Page

---
title: "About Us"
description: "Learn about our team and mission"
roles: ["Guest", "Member", "CoreTeam", "Admin"]
---

Member-Protected Content

---
title: "Team Resources"
description: "Internal resources and documentation"
roles: ["Member", "CoreTeam", "Admin"]
status: "published"
tags: ["resources", "internal"]
sidebar:
  label: "📚 Resources"
  order: 2
---

Admin Guide with All Features

---
title: "Advanced Configuration"
description: "Complete guide to advanced system configuration"
roles: ["Admin"]
status: "published"
tags: ["configuration", "advanced", "admin", "system"]
sidebar:
  label: "⚙️ Advanced Config"
  order: 10
  badge:
    text: "Advanced"
    variant: "caution"
lastUpdated: 2024-12-11T00:00:00.000Z
pagefind: true
---

Draft Content

---
title: "Upcoming Features"
description: "Documentation for features in development"
roles: ["Admin"]
status: "draft"
tags: ["features", "upcoming", "draft"]
sidebar:
  label: "🚧 Upcoming"
  order: 20
---

Schema Validation

The frontmatter is validated against the schema defined in src/content/config.ts. Common validation errors:

• Missing required fields (title, description, roles)
• Invalid role names
• Invalid status values
• Incorrect date formats

Best Practices

1. Always include required fields: title, description, roles
2. Use descriptive tags for better categorization and search
3. Set appropriate sidebar order for logical navigation structure
4. Update lastUpdated when making significant changes
5. Use status: "draft" for work-in-progress pages
6. Consider pagefind: false for sensitive or temporary content
7. Choose the right file extension: .md for simple content, .mdx for interactive content
8. Place files in the correct directory based on intended access level

Common Patterns

Creating a New Guide

---
title: "New Feature Guide"
description: "How to use the new feature"
roles: ["Member", "CoreTeam", "Admin"]
tags: ["guide", "feature", "tutorial"]
sidebar:
  label: "📖 Feature Guide"
  order: 5
status: "draft"  # Start with draft, update to published when ready
---

Policy Documentation

---
title: "Policy Name"
description: "Official policy documentation"
roles: ["CoreTeam", "Admin"]
tags: ["policy", "official", "internal"]
status: "published"
pagefind: true  # Make discoverable in search
---

Archive Old Content

---
title: "Old System Documentation"
description: "Legacy system documentation"
roles: ["Admin"]
status: "archived"
archiveDate: "2024-01-15"
archivedReason: "System replaced by new platform"
tags: ["legacy", "archived"]
---

Remember: The frontmatter controls not just metadata but also who can see your content and how it appears in the site navigation!