koko_blog/README.md

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

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:

---
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