@mars-stack/cli 0.2.0 → 0.2.2

package/template/.cursor/skills/add-blog/SKILL.md

@@ -0,0 +1,447 @@
+# Skill: Add Blog
+
+Set up an MDX-based blog with frontmatter, listing pages, RSS feed, and SEO in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add a blog, create a content section, set up MDX pages, or add articles/posts to the app.
+
+## Prerequisites
+
+- Next.js app set up with the MARS template
+- `appConfig.features.blog` set to `true` in `src/config/app.config.ts`
+
+## Architecture
+
+The blog uses MDX files stored in the repository with filesystem-based routing. Each post is an `.mdx` file with YAML frontmatter. The system provides:
+1. **Content directory** — `content/blog/` at the project root
+2. **Frontmatter schema** — validated with Zod
+3. **Listing page** — paginated blog index with metadata
+4. **Post page** — individual post rendering with table of contents
+5. **RSS feed** — auto-generated `feed.xml`
+6. **SEO** — JSON-LD structured data and Open Graph tags
+
+## Step 1: Install Dependencies
+
+```bash
+yarn add @next/mdx @mdx-js/loader @mdx-js/react gray-matter reading-time remark-gfm rehype-pretty-code
+yarn add -D @types/mdx
+```
+
+## Step 2: Directory Structure
+
+```
+content/
+└── blog/
+    ├── getting-started.mdx
+    └── building-with-mars.mdx
+
+src/
+├── features/blog/
+│   ├── server/
+│   │   └── index.ts          # Post loading, parsing, RSS generation
+│   ├── components/
+│   │   ├── PostCard.tsx       # Blog listing card
+│   │   ├── PostHeader.tsx     # Post title, date, reading time
+│   │   ├── TableOfContents.tsx
+│   │   └── index.ts
+│   ├── validation/
+│   │   └── schemas.ts        # Frontmatter schema
+│   └── types.ts
+├── app/
+│   └── blog/
+│       ├── page.tsx           # Blog listing
+│       └── [slug]/
+│           └── page.tsx       # Individual post
+│   └── feed.xml/
+│       └── route.ts           # RSS feed
+```
+
+## Step 3: Frontmatter Schema
+
+```typescript
+// src/features/blog/validation/schemas.ts
+import { z } from 'zod';
+
+export const frontmatterSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().min(1).max(160),
+  date: z.string().refine((val) => !isNaN(Date.parse(val)), 'Invalid date'),
+  author: z.string().default('Team'),
+  tags: z.array(z.string()).default([]),
+  image: z.string().optional(),
+  published: z.boolean().default(true),
+});
+
+export type Frontmatter = z.infer<typeof frontmatterSchema>;
+```
+
+## Step 4: Blog Types
+
+```typescript
+// src/features/blog/types.ts
+import type { Frontmatter } from './validation/schemas';
+
+export interface BlogPost {
+  slug: string;
+  frontmatter: Frontmatter;
+  content: string;
+  readingTime: string;
+  excerpt: string;
+}
+```
+
+## Step 5: Server-Side Post Loading
+
+```typescript
+// src/features/blog/server/index.ts
+import 'server-only';
+
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import readingTime from 'reading-time';
+import { frontmatterSchema, type Frontmatter } from '../validation/schemas';
+import type { BlogPost } from '../types';
+
+const CONTENT_DIR = path.join(process.cwd(), 'content', 'blog');
+
+export function getAllPosts(): BlogPost[] {
+  if (!fs.existsSync(CONTENT_DIR)) return [];
+
+  const files = fs.readdirSync(CONTENT_DIR).filter((f) => f.endsWith('.mdx'));
+
+  const posts = files
+    .map((filename) => {
+      const slug = filename.replace(/\.mdx$/, '');
+      const filePath = path.join(CONTENT_DIR, filename);
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const { data, content } = matter(raw);
+
+      const parsed = frontmatterSchema.safeParse(data);
+      if (!parsed.success) {
+        console.warn(`Invalid frontmatter in ${filename}:`, parsed.error.message);
+        return null;
+      }
+
+      if (!parsed.data.published) return null;
+
+      const stats = readingTime(content);
+      const excerpt = content.replace(/^#+\s.*$/gm, '').trim().slice(0, 200) + '...';
+
+      return {
+        slug,
+        frontmatter: parsed.data,
+        content,
+        readingTime: stats.text,
+        excerpt,
+      };
+    })
+    .filter(Boolean) as BlogPost[];
+
+  return posts.sort(
+    (a, b) => new Date(b.frontmatter.date).getTime() - new Date(a.frontmatter.date).getTime(),
+  );
+}
+
+export function getPostBySlug(slug: string): BlogPost | null {
+  const filePath = path.join(CONTENT_DIR, `${slug}.mdx`);
+
+  if (!fs.existsSync(filePath)) return null;
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const { data, content } = matter(raw);
+
+  const parsed = frontmatterSchema.safeParse(data);
+  if (!parsed.success) return null;
+
+  const stats = readingTime(content);
+  const excerpt = content.replace(/^#+\s.*$/gm, '').trim().slice(0, 200) + '...';
+
+  return {
+    slug,
+    frontmatter: parsed.data,
+    content,
+    readingTime: stats.text,
+    excerpt,
+  };
+}
+
+export function generateRSSFeed(posts: BlogPost[], siteUrl: string): string {
+  const items = posts
+    .map(
+      (post) => `
+    <item>
+      <title><![CDATA[${post.frontmatter.title}]]></title>
+      <link>${siteUrl}/blog/${post.slug}</link>
+      <guid isPermaLink="true">${siteUrl}/blog/${post.slug}</guid>
+      <description><![CDATA[${post.frontmatter.description}]]></description>
+      <pubDate>${new Date(post.frontmatter.date).toUTCString()}</pubDate>
+      ${post.frontmatter.tags.map((tag) => `<category>${tag}</category>`).join('\n      ')}
+    </item>`,
+    )
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>Blog</title>
+    <link>${siteUrl}/blog</link>
+    <description>Latest posts</description>
+    <atom:link href="${siteUrl}/feed.xml" rel="self" type="application/rss+xml" />
+    ${items}
+  </channel>
+</rss>`;
+}
+```
+
+## Step 6: Blog Listing Page
+
+```typescript
+// src/app/blog/page.tsx
+import { Metadata } from 'next';
+import { getAllPosts } from '@/features/blog/server';
+import { PostCard } from '@/features/blog/components/PostCard';
+
+export const metadata: Metadata = {
+  title: 'Blog',
+  description: 'Latest articles and updates',
+};
+
+export default function BlogPage() {
+  const posts = getAllPosts();
+
+  return (
+    <div className="mx-auto max-w-4xl px-4 py-12">
+      <h1 className="text-3xl font-bold text-content-primary">Blog</h1>
+      <p className="mt-2 text-content-secondary">Latest articles and updates</p>
+
+      <div className="mt-8 space-y-8">
+        {posts.length === 0 && (
+          <p className="text-content-tertiary">No posts yet. Add .mdx files to content/blog/.</p>
+        )}
+        {posts.map((post) => (
+          <PostCard key={post.slug} post={post} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Step 7: Post Card Component
+
+```typescript
+// src/features/blog/components/PostCard.tsx
+import Link from 'next/link';
+import type { BlogPost } from '../types';
+
+export function PostCard({ post }: { post: BlogPost }) {
+  const date = new Date(post.frontmatter.date).toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  });
+
+  return (
+    <article className="group">
+      <Link href={`/blog/${post.slug}`} className="block">
+        <div className="rounded-lg border border-border-primary bg-surface-primary p-6 transition-colors hover:border-interactive-primary">
+          <div className="flex items-center gap-3 text-sm text-content-tertiary">
+            <time dateTime={post.frontmatter.date}>{date}</time>
+            <span aria-hidden="true">&middot;</span>
+            <span>{post.readingTime}</span>
+          </div>
+          <h2 className="mt-2 text-xl font-semibold text-content-primary group-hover:text-interactive-primary">
+            {post.frontmatter.title}
+          </h2>
+          <p className="mt-2 text-content-secondary">{post.frontmatter.description}</p>
+          {post.frontmatter.tags.length > 0 && (
+            <div className="mt-3 flex flex-wrap gap-2">
+              {post.frontmatter.tags.map((tag) => (
+                <span
+                  key={tag}
+                  className="rounded-full bg-surface-secondary px-2.5 py-0.5 text-xs font-medium text-content-secondary"
+                >
+                  {tag}
+                </span>
+              ))}
+            </div>
+          )}
+        </div>
+      </Link>
+    </article>
+  );
+}
+```
+
+## Step 8: Individual Post Page
+
+```typescript
+// src/app/blog/[slug]/page.tsx
+import { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { getAllPosts, getPostBySlug } from '@/features/blog/server';
+import { PostHeader } from '@/features/blog/components/PostHeader';
+import { appConfig } from '@/config/app.config';
+
+interface PostPageProps {
+  params: Promise<{ slug: string }>;
+}
+
+export async function generateStaticParams() {
+  const posts = getAllPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+
+export async function generateMetadata({ params }: PostPageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post) return {};
+
+  const siteUrl = process.env.APP_URL || 'http://localhost:3000';
+
+  return {
+    title: post.frontmatter.title,
+    description: post.frontmatter.description,
+    openGraph: {
+      title: post.frontmatter.title,
+      description: post.frontmatter.description,
+      type: 'article',
+      publishedTime: post.frontmatter.date,
+      url: `${siteUrl}/blog/${slug}`,
+      images: post.frontmatter.image ? [{ url: post.frontmatter.image }] : [],
+    },
+  };
+}
+
+export default async function PostPage({ params }: PostPageProps) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post) notFound();
+
+  const siteUrl = process.env.APP_URL || 'http://localhost:3000';
+
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline: post.frontmatter.title,
+    description: post.frontmatter.description,
+    datePublished: post.frontmatter.date,
+    author: { '@type': 'Person', name: post.frontmatter.author },
+    url: `${siteUrl}/blog/${slug}`,
+  };
+
+  return (
+    <article className="mx-auto max-w-3xl px-4 py-12">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <PostHeader
+        title={post.frontmatter.title}
+        date={post.frontmatter.date}
+        author={post.frontmatter.author}
+        readingTime={post.readingTime}
+        tags={post.frontmatter.tags}
+      />
+      <div className="prose prose-neutral dark:prose-invert mt-8 max-w-none">
+        {/* Render MDX content here using your MDX pipeline */}
+      </div>
+    </article>
+  );
+}
+```
+
+## Step 9: RSS Feed Route
+
+```typescript
+// src/app/feed.xml/route.ts
+import { getAllPosts, generateRSSFeed } from '@/features/blog/server';
+
+export async function GET() {
+  const posts = getAllPosts();
+  const siteUrl = process.env.APP_URL || 'http://localhost:3000';
+  const feed = generateRSSFeed(posts, siteUrl);
+
+  return new Response(feed, {
+    headers: {
+      'Content-Type': 'application/xml',
+      'Cache-Control': 'public, max-age=3600, s-maxage=3600',
+    },
+  });
+}
+```
+
+## Step 10: Sample Post
+
+```markdown
+---
+title: "Getting Started with Your App"
+description: "A quick guide to setting up and customizing your new application."
+date: "2025-01-15"
+author: "Team"
+tags: ["getting-started", "tutorial"]
+published: true
+---
+
+# Getting Started
+
+Welcome to your new application! This guide walks you through the basics.
+
+## Prerequisites
+
+Make sure you have the following installed:
+- Node.js 18+
+- Yarn
+
+## Next Steps
+
+Explore the dashboard and customize your settings.
+```
+
+## Step 11: Next.js MDX Configuration
+
+Update `next.config.mjs`:
+
+```typescript
+import createMDX from '@next/mdx';
+import remarkGfm from 'remark-gfm';
+
+const withMDX = createMDX({
+  options: {
+    remarkPlugins: [remarkGfm],
+    rehypePlugins: [],
+  },
+});
+
+const nextConfig = {
+  pageExtensions: ['ts', 'tsx', 'md', 'mdx'],
+  // ... existing config
+};
+
+export default withMDX(nextConfig);
+```
+
+## Testing
+
+1. Create a `.mdx` file in `content/blog/` — verify it appears on `/blog`.
+2. Click a post — verify the individual page renders with correct metadata.
+3. Visit `/feed.xml` — verify valid RSS with all published posts.
+4. Add a post with `published: false` — verify it is excluded from the listing and feed.
+5. Check Open Graph tags with a social card validator.
+6. Verify JSON-LD structured data with Google's Rich Results Test.
+
+## Checklist
+
+- [ ] MDX dependencies installed (`@next/mdx`, `gray-matter`, `reading-time`, etc.)
+- [ ] `content/blog/` directory created with at least one sample post
+- [ ] Frontmatter schema validates all post metadata
+- [ ] Blog listing page renders all published posts sorted by date
+- [ ] Individual post page renders MDX content with metadata
+- [ ] RSS feed generated at `/feed.xml`
+- [ ] JSON-LD structured data on each post page
+- [ ] Open Graph metadata for social sharing
+- [ ] `generateStaticParams` enables static generation
+- [ ] `next.config.mjs` updated for MDX support
+- [ ] Feature flag checked (`appConfig.features.blog`)