Spotlight Portfolio Guide
This skill provides guidance for working with the Spotlight template from Tailwind Plus - a personal portfolio/blog site built with Next.js 14, TypeScript, and Tailwind CSS v4.
Development Commands
When working with this codebase, use these commands:
`npm install` - Install dependencies`npm run dev` - Start development server (runs on http://localhost:3000)`npm run build` - Build for production`npm run start` - Start production server`npm run lint` - Run ESLintEnvironment Setup
The site requires a `.env.local` file in the root directory:
```
NEXT_PUBLIC_SITE_URL=https://example.com
```
This is required for RSS feed generation.
Project Architecture Overview
Core Architecture Patterns
**App Router**: Uses Next.js 13+ app directory structure located in `src/app/`**MDX Content**: Blog posts are authored in MDX format with frontmatter metadata**File-based Routing**: Posts follow the pattern `src/app/blog/[slug]/page.mdx`**Component-based Layout**: Centralized `Layout` component with `Header` and `Footer`**Dark Mode**: Implemented via `next-themes` with system/manual toggle support**TypeScript Paths**: Uses `@/*` alias mapping to `src/*` directoryContent Management System
The blog system is powered by `src/lib/posts.ts` which:
Dynamically imports MDX files using webpack's context APIUses `fast-glob` to discover all `*/page.mdx` files in the blog directoryExtracts metadata from each post's exported `article` objectProvides functions for fetching all posts and single post by slugStyling System
**Tailwind CSS v4**: Latest version with new CSS-first architecture**Typography Plugin**: `@tailwindcss/typography` for prose styling**Headless UI**: For accessible interactive components (menus, modals, etc.)**Custom Components**: Modular components in `src/components/`MDX Configuration
Located in `next.config.mjs`:
**Remark Plugins**: `remark-gfm` for GitHub Flavored Markdown support**Rehype Plugins**: `@mapbox/rehype-prism` for syntax highlighting**Custom Styles**: Prism CSS styles in `src/styles/prism.css`**Component Overrides**: Global MDX component overrides in `mdx-components.tsx`Working with Blog Posts
Creating a New Blog Post
1. Create a new directory: `src/app/blog/[slug]/`
2. Add a `page.mdx` file with this structure:
```typescript
export const article = {
title: 'Your Post Title',
description: 'A brief description of your post',
author: 'Your Name',
date: 'YYYY-MM-DD'
}
Your Post Title
Your content here in MDX format...
```
3. Place any images in: `public/images/blog/[slug]/`
4. Reference images using: `/images/blog/[slug]/image.png`
Post Metadata Requirements
Each post must export an `article` object containing:
`title` (string): Post title`description` (string): Post description (used in RSS and meta tags)`author` (string): Author name`date` (string): Publication date in YYYY-MM-DD formatMDX Capabilities
Posts support full MDX features:
React componentsJavaScript expressionsImport statementsCustom components defined in `mdx-components.tsx`RSS Feed Generation
The RSS feed is automatically generated at `/feed.xml` by:
1. `src/app/feed.xml/route.ts` - Main feed generation logic
2. Uses the `feed` library to create RSS XML
3. Uses `cheerio` for HTML parsing and content extraction
4. Dynamically discovers all posts using the posts library
5. Fetches rendered HTML for each post to extract full content
**Important**: Requires `NEXT_PUBLIC_SITE_URL` environment variable to be set.
Key Files Reference
`src/lib/posts.ts` - Post discovery and metadata extraction logic`src/components/Layout.tsx` - Main layout wrapper (Header + Footer)`src/components/PostLayout.tsx` - Blog post layout wrapper`src/app/layout.tsx` - Root layout with metadata and theme providers`next.config.mjs` - MDX configuration and Next.js settings`mdx-components.tsx` - Global MDX component overridesComponent Architecture Guidelines
When working with or creating components:
**Location**: Place reusable components in `src/components/`**Composition**: Follow existing patterns (Layout wraps Header/Footer, PostLayout wraps Container/Prose)**Styling**: Use Tailwind CSS classes with dark mode variants (`dark:`)**TypeScript**: Maintain full type safety with proper interfaces/types**Accessibility**: Follow Headless UI patterns for interactive componentsCommon Tasks
Adding Dark Mode Support to Components
Use the `next-themes` hook:
```typescript
import { useTheme } from 'next-themes'
const { theme, setTheme } = useTheme()
```
Apply dark mode variants using Tailwind's `dark:` prefix:
```tsx
<div className="bg-white dark:bg-gray-900">
```
Modifying Site Metadata
Edit `src/app/layout.tsx`:
Update `metadata` export for title, description, OpenGraph tagsModify `<html>` attributes for language or other settingsCustomizing MDX Components
Edit `mdx-components.tsx` to override default MDX elements:
```typescript
export function useMDXComponents(components: MDXComponents): MDXComponents {
return {
h1: ({ children }) => <h1 className="custom-class">{children}</h1>,
...components,
}
}
```
Adding New Routes
Follow Next.js App Router conventions:
Page: `src/app/[route]/page.tsx`Layout: `src/app/[route]/layout.tsx`Loading: `src/app/[route]/loading.tsx`Error: `src/app/[route]/error.tsx`Deployment Considerations
Set `NEXT_PUBLIC_SITE_URL` to production domainEnsure all images are optimized and in `public/` directoryRun `npm run build` to verify production build succeedsRSS feed will automatically generate at build timeTroubleshooting
**RSS feed not generating**: Verify `NEXT_PUBLIC_SITE_URL` is set in environment
**MDX not rendering**: Check `next.config.mjs` has MDX plugin configured
**Dark mode not working**: Ensure `ThemeProvider` is in root layout and components use dark mode variants
**Images not loading**: Verify images are in `public/` and paths start with `/`