Content Authoring Guidelines

This document provides guidelines for creating and managing content within projects built with this Astro Performance Starter template.

Getting Started

• Content Location: All structured content uses Astro’s Content Collections API in src/content/
• Validation: Run pnpm run check to validate TypeScript and content schemas
• Configuration: Content collection schemas are defined in src/content.config.ts

Content Collections Setup

The template ships six content collections — projects, blog, navigation, bio, experience, and adr — that you can extend:

Blog Collection Example

// src/content.config.ts (excerpt — see the file for all six collections)
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blogCollection = defineCollection({
  loader: glob({ pattern: "**/[^_]*.{md,mdx}", base: "./src/content/blog" }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      description: z.string().max(160), // SEO meta description
      date: z.date(),
      updated: z.date().optional(),
      draft: z.boolean().default(false),
      featured: z.boolean().default(false),
      cover: image().optional(),
      coverAlt: z.string(), // Required for accessibility when cover is used
      tags: z.array(z.string()).default([]),
      author: z.string().default("Your Name"),
    }),
});

export const collections = {
  projects: projectsCollection,
  blog: blogCollection,
  navigation: navigationCollection,
  bio: bioCollection,
  experience: experienceCollection,
  adr: adrCollection,
};

Creating Content

1. Create collection directory: src/content/[collection-name]/
2. Add content files: Use .md or .mdx format
3. Include frontmatter: Match your schema requirements
4. Validate: Run pnpm run check to ensure type safety

Using MDX Components

The template supports MDX for rich content with React-like components:

---
title: "Example Post"
description: "Demonstrating MDX components"
date: 2024-01-01
---

import { Image } from 'astro:assets';
import exampleImage from './example.jpg';

# My Post

Regular markdown content works as expected.

<Image src={exampleImage} alt="Example image" />

You can also use any Astro components in your MDX files.

Figure, Grid, and Callout (from src/components/mdx/) are pre-registered and need no import; anything else — including Image — must be imported inside the MDX file.

Image Guidelines

• Location: Store images next to content files or in src/assets/
• Optimization: Use the built-in <Image /> component for automatic optimization
• Formats: images are optimized to a single output format — the template’s Image atom defaults to AVIF (SVGs pass through unchanged)
• Alt text: Always include descriptive alt text for accessibility

---
import { Image } from 'astro:assets';
import myImage from '../assets/example.jpg';
---

<Image src={myImage} alt="Descriptive alt text" />

Content Workflow

1. Plan content structure using Content Collections
2. Create schema in src/content.config.ts
3. Write content in MDX format with proper frontmatter
4. Preview locally with pnpm dev
5. Validate with pnpm run check
6. Deploy using your preferred hosting platform