blog.patriciomarroquin.dev – Personal Developer Blog

A modern, fast developer blog built with Astro, React, TypeScript, Tailwind 4, and an AI-powered content pipeline.

---

✨ Features

• 🌗 Dark / Light mode

  • Respects system preference (prefers-color-scheme)
  • Manual toggle powered by a data-theme attribute

• 📰 MDX-powered blog

  • Articles live in src/content/articles/*.mdx
  • Custom BlogPost.astro layout with consistent typography and spacing
  • Reading time, publication meta, tags, and category badges

• 🔊 Reading experience upgrades

  • Reading progress bar (top of the article)
  • Estimated reading time
  • Text-to-speech mode: “Listen / Stop listening” button that reads:
    • Title
    • Description
    • Full article body

• 🧑‍💻 Beautiful code blocks

  • Shiki-based syntax highlighting via Astro’s markdown pipeline
  • Custom CodeBlock.astro wrapper for MDX
  • “Traffic light” header + language label + Copy button
  • Optional filename="yourfile.tsx" meta support in code fences

• 📅 Content calendar

  • src/pages/calendar.astro + ContentCalendarPage.tsx
  • Reads monthly plans from content-plans/*.json
  • Shows:
    • Planned vs Published articles
    • Category color dots (🔥 Trending, 📚 Tutorial, 🔬 Deep Dive)
    • Upcoming articles list
  • Published entries link directly to /blog/[slug]

• 🤖 AI-powered content pipeline

  • Monthly content plan generator (JSON under content-plans/)
  • Daily article generator (MDX under src/content/articles/)
  • Uses OpenAI’s Responses API
  • GitHub Actions open PRs so content can be reviewed before publishing

• 🔍 Full-text search (Pagefind)

  • Static search index generated after each build
  • Client-side search modal (SearchModal.tsx) with:
    • Debounced queries
    • Keyboard navigation (↑ / ↓ / ↵ / ESC)
    • Recent searches stored in localStorage
  • Results show title, excerpt, category badge, and tags

• 🌐 Production ready

  • Astro static site generation
  • Deployed on Vercel
  • Vercel Web Analytics enabled
  • SEO-friendly structure + sitemap

---

🚀 Quick Start

This project uses pnpm.

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production (static output)
pnpm build

# Preview the production build
pnpm preview

Linting (if configured)

pnpm lint

---

🤖 Content Automation

Two scripts handle content planning and generation.

1) Generate monthly content plan

Creates/updates a JSON file in content-plans/YYYY-MM.json with a schedule of articles for the month (category, title, slug, angle, outline, etc.).

pnpm generate:plan

• Looks at the current month (e.g. "2025-12")
• Keeps existing months; doesn’t overwrite unrelated data
• Used by the Content Calendar page

2) Generate today’s article from the plan

Reads the month’s plan, finds today’s entry, and generates a full MDX article file (with frontmatter + body):

pnpm generate:article

• Output: src/content/articles/YYYY-MM-DD-slug-from-plan.mdx

• Uses:

  • Your outlined sections
  • Code ideas
  • Media ideas (images/diagrams)

• Enforces:

  • Real, useful content (not fluff)

  • Multiple code snippets

  • Optional filename="..." in code fences for better code block headers

  • Final signature:

    Until next time, happy coding 👨‍💻  
    – Juan Patricio 💜

⚠️ These scripts require OPENAI_API_KEY in your .env.

---

🔁 GitHub Actions (Automation Overview)

(File names are suggestions; adjust if you named them differently.)

.github/workflows/content-plan.yml

• Runs: monthly, on the 1st (e.g. 0 9 1 * *)
• Does:
  • Checks out the repo
  • Runs pnpm generate:plan
  • Commits the updated content-plans/YYYY-MM.json
  • Opens a PR with a conventional commit-style message, e.g.:
    • feat(content): add content plan for 2025-12

.github/workflows/generate-article.yml

• Runs: daily around midday (UTC / chosen TZ)
• Does:
  • Checks out the repo
  • Runs pnpm generate:article
  • If a new article is generated:
    • Commits the MDX file under src/content/articles/
    • Opens a PR, e.g.:
      • feat(article): add post for 2025-12-06

This keeps you in the loop: AI proposes, you review & merge.

---

🔍 Full-text Search

Search is powered by Pagefind and runs entirely on the client.

How it works

• After astro build, a post-build script runs:

  pnpm build
  # -> astro build
  # -> node scripts/build-search-index.mjs

• scripts/build-search-index.mjs:

  • Detects the correct static output directory:

    • Uses .vercel/output/static when deployed on Vercel (Astro + Vercel adapter)
    • Falls back to dist when running locally

  • Runs Pagefind against that directory:

    npx pagefind --site "<output-dir>"

  • Generates the search bundle and index under /pagefind (including pagefind.js), alongside other static assets.

Frontend integration (SearchModal.tsx)

• The search modal dynamically loads the Pagefind client at runtime:

  const pagefind = await import(/* @vite-ignore */ "/pagefind/pagefind.js");

• It performs pagefind.search(query) and maps each result to:

  • url
  • title
  • excerpt (HTML stripped to plain text)
  • meta.category
  • meta.tags
  • meta.publish_date

• UX features:

  • Debounced search requests
  • Keyboard navigation (↑ / ↓ / ↵ / ESC)
  • Loading and “no results” states
  • Recent searches stored in localStorage with a “Clear” option
  • Result cards showing title, excerpt, category badge, and tags

All searching happens client-side on top of the static HTML generated by Astro, so the site remains fast, statically hosted, and independent of external search services.

---

📁 Project Structure

High-level overview of the Astro + React + MDX setup.

src/
├── components/
│   ├── ui/                    # Reusable UI primitives
│   │   ├── Button.tsx
│   │   ├── Tag.tsx
│   │   ├── CodeContainer.tsx  # React version (for non-MDX usage)
│   │   └── ThemeToggle.tsx
│   ├── articles/
│   │   ├── ArticleCard.tsx
│   │   └── ArticleCategoryBadge.tsx
│   └── layout/
│       ├── Navbar.tsx
│       ├── MobileNav.tsx
│       └── Footer.tsx
├── content/
│   └── articles/              # MDX blog posts
│       ├── 2025-12-06-react-19-....mdx
│       └── ...
├── layouts/
│   ├── BaseLayout.astro       # Shared shell for pages
│   └── BlogPost.astro         # Article layout (reading UX, TTS, etc.)
├── pages/
│   ├── index.astro            # Home / landing
│   ├── blog/
│   │   ├── index.astro        # Blog index
│   │   └── [slug].astro       # Article detail route
│   └── calendar.astro         # Content calendar page
├── views/
│   ├── HomePage.tsx           # React "view" components
│   ├── BlogIndexPage.tsx
│   ├── ArticleListPage.tsx
│   └── ContentCalendarPage.tsx
├── hooks/
│   ├── useReadingProgress.ts  # Scroll → progress bar value
│   └── useTheme.tsx           # ThemeProvider + useTheme
├── utils/
│   ├── index.ts               # cn(), formatDate(), etc.
│   └── calendar.ts            # getMonthMatrix(), helpers for calendar
├── styles/
│   └── global.css             # Tailwind base + custom prose styles
├── types/
│   └── index.d.ts             # Article & calendar types
└── env.d.ts                   # Astro env typing

There’s also:

content-plans/
└── YYYY-MM.json               # AI-generated content plan per month

scripts/
├── generate-content-plan.mjs        # pnpm generate:plan
└── generate-article-from-plan.mjs   # pnpm generate:article

---

🛠️ Tech Stack

Technology	Purpose
Astro	Static site generator / HTML-first framework
React 19	Interactive islands and UI components
TypeScript	Type safety
Tailwind CSS 4	Utility-first styling (via @tailwindcss/vite)
Shiki	Syntax highlighting for MDX code blocks
Lucide React	Icon set for UI + calendar legend
Vercel	Hosting + analytics
OpenAI Responses API	Content planning & article generation
Pagefind	Static full-text search over generated HTML

---

🎨 Design System

Colors

• Primary: Sky (sky-500)
• Neutrals: Zinc palette
• Categories:
  • 🔥 Trending: Orange
  • 📚 Tutorial: Sky Blue
  • 🔬 Deep Dive: Purple
• Status:
  • ✅ Published: Emerald badge
  • ⏳ Coming soon: Neutral gray badge

Typography

• Sans: Plus Jakarta Sans
• Mono: JetBrains Mono

---

🧩 Code Blocks in MDX

Code blocks in MDX are rendered by CodeBlock.astro and Shiki.

Example with filename:

```ts filename="Profile.server.tsx"
// Profile.server.tsx
import { fetchUserProfile } from "../lib/api";

export default async function Profile() {
  const user = await fetchUserProfile();
  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.bio}</p>
    </div>
  );
}
```

- `language` is picked from the fence (`ts`, `tsx`, etc.)
- `filename` is parsed from the meta string and displayed in the header
- The copy button uses a delegated click handler + `navigator.clipboard`

---

## 📝 Content Types

```ts
export type ArticleCategory = "trending" | "tutorial" | "deep-dive";

export interface Article {
  slug: string;                // e.g. "react-19-biggest-features-i-am-excited-about"
  title: string;
  description: string;
  category: ArticleCategory;
  tags: string[];
  date: string;                // ISO date, e.g. "2025-12-06"
}

export interface CalendarArticle extends Article {
  status: "planned" | "published";
}

On the calendar page:

• Published articles:
  • Green “Published” badge
  • Clickable card → navigates to /blog/[slug]
• Planned articles:
  • Gray “Coming soon” badge
  • Non-clickable card

---

🌗 Theme System

Dark mode is handled via data-theme on <html> plus a small React provider:

type Theme = "light" | "dark";

interface ThemeContextValue {
  theme: Theme;
  toggleTheme: () => void;
}

Flow:

1. Check localStorage for a saved theme.
2. Otherwise, read window.matchMedia("(prefers-color-scheme: dark)").
3. Apply data-theme="light" | "dark" on <html>.
4. Persist user choice when toggled.

---

🔮 Roadmap

• MDX support for article content
• Migrate to Astro for SSG and SEO
• Content calendar view
• AI-generated monthly plan + daily article script
• RSS feed generation
• Full-text search (Pagefind)
• Comments (Giscus)
• Related articles recommendations
• View counter per article
• Search filters (by category / tag)

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

MIT © Juan Patricio Marroquín

---

Built with ☕ and 💜 from Lima, Peru.