Content Management Guide

Complete guide to managing content on the Cascadia Marquee website

Content Management Guide

Complete guide to managing content on the Cascadia Marquee website using MDX and Content Collections.

How content is loaded

Source files: src/content/**/*.mdx (you edit these in Git)
Config: content-collections.ts at the repo root defines schemas and slug rules
Build: Content Collections runs when you pnpm dev or pnpm build (no separate build:content script)
Imports in app code: import { allPosts } from "content-collections"
Rendering: <Mdx code={post.mdx} /> for the page body; post.content is the raw MDX string (TOC, llms-full.txt, SEO helpers)

Content Types

The website supports four main content types:

Blog Posts - Articles, tutorials, and case studies
Documentation - Technical guides and project documentation
Services - Service descriptions and offerings
Legal Documents - Privacy policy, terms of service, etc.

Blog Posts

Adding Blog Posts

Create a new .mdx file in src/content/posts/
Organize by category in subdirectories:
- case-studies/ - Client success stories
- posts/ - General blog posts
- tutorials/ - How-to guides and tutorials

Blog Post Front Matter

---
title: "Your Post Title"
summary: "Brief description of the post content"
date: "2024-01-01"
author: "Author Name"
category: "tutorials" # or "case-studies", "posts"
published: true
featured: false
tags: ["shopify", "theme-customization", "liquid"]
image: "/blog-images/your-image.webp"
---

Blog Post Structure

# Your Post Title
 
Brief introduction paragraph.
 
## Section 1
 
Content for section 1.
 
### Subsection
 
More detailed content.
 
## Section 2
 
Additional content sections.
 
## Conclusion
 
Wrap up your post.

Blog Post Examples

Case Study Example:

---
title: "SP Book a Demo - E-commerce Optimization"
summary: "How we optimized the booking flow for SP's demo system"
date: "2024-01-15"
author: "Carl Hickerson"
category: "case-studies"
published: true
featured: true
tags: ["shopify", "optimization", "case-study"]
image: "/blog-images/sp-book-a-demo.webp"
---

Tutorial Example:

---
title: "How to Optimize Your Shopify Store for Faster Load Times"
summary: "Complete guide to improving Shopify store performance"
date: "2024-01-10"
author: "Carl Hickerson"
category: "tutorials"
published: true
featured: false
tags: ["shopify", "performance", "optimization"]
---

Documentation

Adding Documentation

Create a new .mdx file in src/content/docs/
Use numbered prefixes for ordering:
- 1_guides/ - Technical guides and tutorials
- 2_documentation/ - Project documentation

Documentation Front Matter

---
title: "Documentation Title"
description: "Brief description of the documentation"
published: true
toc: true
updated: "2024-01-01"
author: "Carl Hickerson"
---

Documentation Structure

# Documentation Title
 
Overview of what this documentation covers.
 
## Prerequisites
 
What users need before starting.
 
## Step 1: Setup
 
Detailed instructions.
 
### Sub-step
 
More specific instructions.
 
## Step 2: Configuration
 
Next steps.
 
## Troubleshooting
 
Common issues and solutions.

Services

Adding Services

Create a new .mdx file in src/content/services/
Use numbered prefixes for ordering:
- 1_shopify/ - Shopify-related services
- 2_accessibility/ - Accessibility services
- 3_automation/ - Automation services
- 4_development/ - Custom development
- 5_white-label/ - White-label services

Service Front Matter

---
title: "Service Name"
description: "Brief description of the service"
published: true
toc: true
updated: "2024-01-01"
author: "Carl Hickerson"
---

Service Structure

# Service Name
 
Overview of the service and what it includes.
 
## What We Offer
 
Detailed list of service offerings.
 
## Process
 
How we work with clients.
 
## Pricing
 
Pricing information (if applicable).
 
## Get Started
 
How to begin working with us.

Legal Documents

Adding Legal Documents

Create a new .mdx file in src/content/legal/
Use descriptive filenames:
- privacy-policy.mdx
- terms-of-service.mdx

Legal Document Front Matter

---
title: "Document Title"
description: "Brief description"
published: true
toc: true
updated: "2024-01-01"
---

MDX Features

Using React Components

You can use React components directly in MDX:

import { Callout } from "@/components/callout";
 
# My Post
 
<Callout type="info">This is an info callout using a React component.</Callout>
 
Regular markdown content here.

Available Components

The following components are available in MDX:

<Callout> - Info, warning, error callouts
<Accordion> - Collapsible content sections
<Button> - Interactive buttons
<Card> - Content cards
<Badge> - Status badges
<CodeBlock> - Syntax-highlighted code blocks

Code Blocks

Use fenced code blocks with language specification:

```typescript
const example = "TypeScript code";
console.log(example);
```
 
```bash
npm install package-name
```
 
```jsx
function Component() {
  return <div>JSX code</div>;
}
```

Images

Use the next/image component for optimized images:

import Image from "next/image";
 
<Image src="/blog-images/example.webp" alt="Description of image" width={800} height={600} />

Content Organization

File Naming Conventions

Use kebab-case for filenames: my-blog-post.mdx
Use descriptive names that reflect the content
Include dates for time-sensitive content: 2024-01-15-my-post.mdx

Directory Structure

src/content/
├── docs/
│   ├── 1_guides/
│   │   ├── 1_google/
│   │   │   ├── 1_google-calendar-setup.mdx
│   │   │   └── 2_domain-wide-delegation-setup.mdx
│   │   └── 2_framer-motion/
│   │       ├── 1_framer-motion-guide.mdx
│   │       └── animation-recipes.mdx
│   └── 2_documentation/
│       ├── 1_development-setup.mdx
│       ├── 2_content-management.mdx
│       ├── 3_component-development.mdx
│       ├── 4_build-deployment.mdx
│       └── changelog.mdx
├── posts/
│   ├── case-studies/
│   │   ├── sp-book-a-demo.mdx
│   │   └── sp-configurator.mdx
│   ├── posts/
│   │   └── my-first-post.mdx
│   └── tutorials/
│       └── how-to-optimize-your-shopify-store.mdx
├── services/
│   ├── 1_shopify/
│   │   └── 1_shopify-development.mdx
│   ├── 2_accessibility/
│   │   └── 2_accessibility-compliance.mdx
│   └── index.mdx
└── legal/
    ├── privacy-policy.mdx
    └── terms-of-service.mdx

Content Workflow

1. Planning

Outline your content before writing
Research keywords for SEO optimization
Gather assets (images, code examples, etc.)

2. Writing

Use clear headings for better structure
Include code examples where relevant
Add images to break up text
Write descriptive alt text for accessibility

3. Review

Check front matter for accuracy
Verify links and references
Test code examples if applicable
Review for typos and grammar

4. Publishing

Set published: true in front matter
Add appropriate tags for categorization
Update navigation if needed
Test the published content

SEO Best Practices

Front Matter SEO

---
title: "SEO-Optimized Title"
description: "Meta description for search engines"
published: true
tags: ["relevant", "keywords", "for", "seo"]
image: "/blog-images/seo-image.webp"
---

Content SEO

Use descriptive headings (H1, H2, H3)
Include relevant keywords naturally
Write compelling meta descriptions
Add alt text to images
Use internal links to related content

Image Optimization

Use WebP format for better compression
Optimize image sizes (800x600 for blog images)
Add descriptive alt text
Use the next/image component

Content Maintenance

Regular Updates

Review and update outdated content
Check for broken links
Update code examples for new versions
Refresh images if needed

Content Audit

Identify popular content for expansion
Find gaps in content coverage
Update navigation based on user needs
Archive outdated content

Troubleshooting

Common Issues

Content not appearing:

Check that published: true is set
Verify file is in the correct directory
Ensure front matter is properly formatted

Images not loading:

Check image path is correct
Verify image exists in public/ directory
Use proper next/image syntax

Code blocks not highlighting:

Specify the correct language
Check for syntax errors
Verify code block formatting

Navigation not updating:

Check navigation configuration files
Verify file naming conventions
Update navigation arrays if needed

Best Practices

Write for your audience - Use clear, accessible language
Be consistent - Follow established patterns and conventions
Test everything - Verify content works as expected
Keep it updated - Regularly review and update content
Optimize for performance - Use optimized images and efficient code
Make it accessible - Include alt text, proper headings, and clear structure

For questions about content management, check the other documentation sections or contact the development team.

Development Setup Component Development