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

User Intent	Action	CLI Function
"Add video [URL]"	Extract metadata → generate tags → create file	addVideo()
"Create course [topic]"	AI outline → scaffold structure	Coming soon
"Deploy site"	Validate → build → tag → push	Coming soon
"Switch theme [name]"	Update .env → preview → commit	Coming soon
"Preview changes"	Build → serve port 4567	./start.sh
"Validate content"	Schema + links + structure check	validateContent()

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:

Collection	Required Fields	Optional
videos	title, author, url	duration, description, tags
podcasts	title, host, url	episode, duration, description
people	name, role, url	bio, tags
products	name, description, url	price, tags
courses	title, provider, url	duration, level, tags
tutorials	title, author, url	duration, difficulty, tags
books	title, author	publisher, isbn, url
repos	title, owner, url	stars, language, tags
tweets	author, content, url	date, tags

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