# Koko Blog

A fast, beautiful personal blog built with Astro, TypeScript, and a synthwave purple theme.

**Load time:** < 100ms | **Bundle size:** < 50KB | **Zero runtime JS by default**

---

## Stack

- **Framework:** Astro 5 — static output, file-based routing, zero JS by default
- **Language:** TypeScript strict
- **Package manager:** pnpm
- **Syntax highlighting:** Shiki / Dracula (built into Astro, zero runtime cost)
- **Image optimization:** `node image-optimizer.js` (WebP via sharp, run before build)
- **Content:** Astro Content Collections with Zod schema

> **For AI agents:** All components are `.astro` files. No React, no Vue, no `.tsx`. Astro uses
> `---` frontmatter fences, not `<template>` or `<script setup>`. File-based routing lives in
> `src/pages/` — no router library needed. If existing files contradict this, ignore them and
> follow this README.

---

## Quick Start

```bash
pnpm install
pnpm dev        # dev server at http://localhost:4321
pnpm build      # production build → dist/
pnpm preview    # preview production build
pnpm check      # TypeScript check (astro check, not tsc)
```

---

## Project Structure

```
koko-blog/
├── public/
│   ├── images/
│   │   ├── posts/          # Blog post hero images
│   │   └── previews/       # WebP-optimised thumbnails
│   └── favicon.svg
├── src/
│   ├── components/         # .astro components only
│   │   ├── Layout.astro    # Base page layout (head, header, footer)
│   │   ├── Header.astro    # Navigation + mobile menu
│   │   ├── Sidebar.astro   # Collapsible sidebar
│   │   ├── Footer.astro
│   │   ├── Hero.astro      # Homepage hero with carousel
│   │   ├── PostCard.astro  # Blog post preview card
│   │   └── PostGrid.astro  # Posts grid layout
│   ├── pages/              # File-based routing (.astro files only)
│   │   ├── index.astro     # Homepage
│   │   ├── posts/
│   │   │   └── [slug].astro  # Individual post page
│   │   └── 404.astro
│   ├── content/
│   │   ├── config.ts       # Zod schema for blog collection
│   │   └── blog/           # Markdown posts (.md files)
│   ├── styles/
│   │   ├── synthwave.css   # CSS custom properties (theme variables)
│   │   └── global.css      # Resets and base styles
│   └── env.d.ts            # /// <reference types="astro/client" />
├── image-optimizer.js      # WebP conversion (run: node image-optimizer.js)
├── astro.config.mjs        # Astro config (output: static, shiki/dracula)
├── tsconfig.json           # extends astro/tsconfigs/strict + path aliases
├── PLAN.md
└── TODO.md
```

---

## Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start dev server (port 4321) |
| `pnpm build` | Build for production |
| `pnpm preview` | Preview production build |
| `pnpm check` | Type-check with `astro check` |
| `node image-optimizer.js` | Convert images to WebP (run before build) |

---

## Design System

### Colors

| Token | Hex | Usage |
|-------|-----|-------|
| Primary | `#6a1b9a` | Buttons, accents, links |
| Primary Dark | `#510ca9` | Hover states |
| Secondary | `#000080` | Electronic sheen elements |
| Background | `#000000` | Page background |
| Paper | `#121212` | Card backgrounds |
| Text Primary | `#ffffff` | Headings |
| Text Secondary | `#eeeeee` | Body text |
| Text Muted | `#888888` | Metadata |

### Typography

- **Headlines:** 2.5rem–4rem, weight 800
- **Titles:** 1.8rem, weight 700
- **Body:** 1rem, line-height 1.8
- **Code:** Monospace, dark background (Shiki/Dracula)

### Breakpoints

- **Mobile:** < 768px
- **Tablet:** 768px–1024px
- **Desktop:** > 1024px

---

## Writing Content

Posts live in `src/content/blog/` as `.md` files with YAML frontmatter:

```markdown
---
title: "My Awesome Post"
slug: "my-awesome-post"
excerpt: "A brief description..."
publishedAt: "2026-02-28"
category: "Game Development"
tags: ["unity", "csharp"]
image: "/images/posts/hero.jpg"
draft: false
---

Your content here with **markdown** support.

```typescript
// Syntax highlighting via Shiki/Dracula — zero runtime JS
const hello = "world";
```
```

---

## TypeScript Path Aliases

```typescript
import Layout from '@components/Layout.astro';
import '@styles/global.css';
```

Available aliases (defined in `tsconfig.json`):
- `@/*` → `./src/*`
- `@components/*` → `./src/components/*`
- `@layouts/*` → `./src/layouts/*`
- `@styles/*` → `./src/styles/*`
- `@utils/*` → `./src/utils/*`

---

## Performance Targets

| Metric | Target |
|--------|--------|
| Load time | < 100ms |
| Bundle size | < 50KB (gzipped) |
| First Contentful Paint | < 50ms |
| Largest Contentful Paint | < 1s |
| Lighthouse score | > 90 |

---

**Built with:** Astro • TypeScript • pnpm