Blog-CC Content Management

⚠️ VERIFICATION REQUIRED

BEFORE using this skill, verify this is a blog-cc project:

1. Check for content/ directory with collections/, pages/, or courses/ subdirectories
2. Check for next.config.js with basePath config OR CONTENT-GUIDE.md
3. Check for theme system: lib/themes/ directory
4. When uncertain: ASK the user "Is this a blog-cc project?"

NOT blog-cc if:

• Hugo, Jekyll, Gatsby, or other SSG (different file structure)
• WordPress or database-backed CMS
• Plain HTML site without Next.js
• Custom Next.js site without blog-cc content structure

Overview

Blog-cc is a Next.js-based static site generator for AI learning content. This skill provides conversational content management with AI-powered generation, course building, and GitHub Pages deployment.

Core principle: Use TypeScript CLI utilities for operations. Validate before deploying. Git-tag deployments. Preview before publishing.

When to Use

ONLY after verifying blog-cc project, use this skill when you see:

• "Add video [URL]" or "Add content"
• "Create course about [topic]"
• "Deploy site" or "Publish to GitHub Pages"
• "Switch theme to [name]"
• "Validate content"
• "Preview changes"

When NOT to Use

NEVER use this skill for:

• Hugo, Jekyll, Gatsby sites (different architecture)
• WordPress or database CMS (not static site)
• Generic Next.js without blog-cc structure
• When project type is unclear - ASK THE USER FIRST

If uncertain, verify first:

# Check for blog-cc structure
ls content/collections content/pages CONTENT-GUIDE.md
# If missing → NOT blog-cc → DON'T use this skill

Quick Reference

Essential Workflows

Content Creation (AI-Powered)

When user provides URL:

1. Verify project with isBlogCCProject()
2. Call addVideo() with URL only
3. AI extracts YouTube metadata and generates tags/description
4. Show preview to user
5. User confirms or edits
6. Create file: content/collections/[type]/[slug].md
7. Auto-commit: feat: add video 'Title'
8. Offer preview: "Run ./start.sh to see changes"

Three modes:

• URL only: AI extracts all metadata
• Full args: Manual specification
• Interactive: Prompts for each field

Content Validation

Before deployment, always validate:

import { validateContent } from './lib/cli/validation/content-validator'

const result = await validateContent(projectRoot)
// Checks:
// - Required fields per collection type (videos: title, author, url)
// - Duplicate slugs
// - Date formats (YYYY-MM-DD)
// - Course structure (course.md, modules/)

Reports:

• Errors (blocking): Missing required fields, invalid dates, duplicates
• Warnings (non-blocking): Broken links, missing assets
• Files checked count

Never deploy with validation errors.

Collection Types & Schemas

9 supported collection types:

File location: content/collections/[collection-type]/[slug].md

Project Structure

blog-cc-project/
├── content/
│   ├── collections/
│   │   ├── videos/
│   │   ├── tutorials/
│   │   ├── courses/
│   │   └── ... (9 types)
│   ├── pages/           # Blog posts
│   ├── courses/         # Multi-module courses
│   │   └── [slug]/
│   │       ├── course.md
│   │       └── modules/
│   └── home.md
├── lib/
│   └── themes/          # 9 themes
├── .env                 # THEME=moss
├── .env.production      # BASE_PATH=/repo-name
├── next.config.js
└── CONTENT-GUIDE.md

Common Patterns

// Add content from URL (AI extracts metadata)
import { addVideo } from './lib/cli/content/add-video'
await addVideo(projectRoot, { url: 'https://youtube.com/...' })

// Validate before deploy
import { validateContent } from './lib/cli/validation/content-validator'
const result = await validateContent(projectRoot)
if (!result.valid) { console.log(result.errors); process.exit(1) }

// Load project config
import { loadBlogCCConfig } from './lib/cli/utils/config-loader'
const config = await loadBlogCCConfig(projectRoot)

Common Mistakes

1. Not verifying blog-cc project - always check structure first 2. Skipping validation - always validate before deploy 3. Hardcoding paths - use config.contentDir from config loader 4. Creating invalid slugs - slugify: lowercase, replace spaces with dashes 5. Missing frontmatter fields - check schema for required fields per collection 6. Not auto-committing - use autoCommit() from git-helper 7. Forgetting to offer preview - always suggest ./start.sh after changes

Available CLI Utilities

Utils: yaml-handler, project-detector, git-helper, config-loader Content: add-video, ai-generator Validation: content-validator

See lib/cli/ for TypeScript implementations.

Best Practices

• Always verify project before operations
• Use AI extraction when URL provided
• Show preview before creating files
• Validate before deploy (no exceptions)
• Auto-commit changes with descriptive messages
• Offer next steps after operations
• Check for existing files before creating
• Use consistent slugs (lowercase-with-dashes)

Themes

9 themes: iris (default), moss, crimson, ocean, amber, slate, violet, forest, sky

Switch: Update .env THEME → preview → commit

Deployment (Coming Soon)

4-layer safety system:

1. Content validation (schema, links, structure)
2. Pre-deploy checks (build success, git status)
3. Preview (serve locally before push)
4. Rollback (git tags for quick revert)

Deployment flow:

# 1. Validate
validateContent()

# 2. Build
npm run build

# 3. Tag
git tag deploy/site-name/2025-11-03-14-30-00

# 4. Push
git push origin main --tags

# 5. GitHub Pages builds automatically

Additional Resources

• Framework Repo: https://github.com/imehr/blog-cc-framework
• Template Repo: https://github.com/imehr/blog-cc
• CLI docs: TypeScript comments in lib/cli/

When Deployment Fails

CRITICAL: Diagnose before acting. Never guess under pressure.

1. validateContent() - check for validation errors FIRST
2. npm run build - verify build succeeds locally
3. Check GitHub Actions logs in repo → Actions tab
4. Verify .env.production has BASE_PATH=/repo-name
5. Check GitHub Pages settings: Settings → Pages → Source: gh-pages branch

For content issues: validate → fix → rebuild → redeploy For build issues: check logs → fix errors → test locally → redeploy