Keith's Blog 📝

A developer's blog built on the AstroPaper theme, featuring automatic date management, modern tooling, and a focus on developer experience.

🔥 Features

Blog Features

• Type-safe markdown with frontmatter validation
• Automatic date management with Git hooks
• Featured post rotation with smart selection
• Interactive post creation with CLI tools
• Draft posts & pagination support
• Fuzzy search functionality
• Dynamic OG image generation
• RSS feed & sitemap generation

Developer Experience

• Pre-commit hooks for automatic date updates
• Modern tooling (ESLint, Prettier, Husky, lint-staged)
• Cross-platform compatibility (macOS/Linux/Windows)
• CLI tools for post management
• TypeScript support throughout

Performance & Accessibility

• Super fast performance (Lighthouse 100)
• Responsive design (mobile to desktop)
• Accessible (Keyboard/VoiceOver tested)
• SEO-friendly with meta tags
• Light & dark mode support

🚀 Quick Start

Creating New Posts

# Interactive mode - prompts for all details
pnpm new-post

# Command line mode
pnpm new-post "My Post Title" --tags "javascript,tutorial" --featured --published

Managing Post Dates

Dates are automatically managed via Git hooks, but you can also run manually:

# Update dates for changed files
pnpm update-dates

# Force update all posts
pnpm update-dates:force

# Preview changes without writing
pnpm update-dates --dry-run

For more details, see Date Management Documentation.

🚀 Project Structure

/
├── .husky/                  # Git hooks for automation
│   └── pre-commit          # Automatic date management
├── docs/                   # Documentation
│   └── DATE_MANAGEMENT.md  # Date system docs
├── public/                 # Static assets
│   ├── assets/
│   └── pagefind/           # Generated search index
├── scripts/                # Automation scripts
│   ├── new-post.js         # Post creation CLI
│   └── update-post-dates.js # Date management
├── src/
│   ├── components/         # Reusable UI components
│   ├── data/
│   │   └── blog/           # Blog posts (markdown)
│   ├── layouts/            # Page layouts
│   ├── pages/              # Astro pages/routes
│   ├── styles/             # Global styles
│   └── utils/              # Helper functions
├── date-manager.config.json # Optional config
├── .lintstagedrc           # Lint-staged config
└── package.json            # Dependencies & scripts

Key Directories:

• Blog posts: src/data/blog/ - All markdown blog posts
• Scripts: scripts/ - CLI tools for post management
• Documentation: docs/ - Project documentation

📖 Documentation

Blog Management

• Date Management System - Automatic date management with Git hooks
• Theme Configuration - Customize the blog theme
• Adding Posts - Manual post creation guide
• Color Schemes - Customize colors and themes

💻 Tech Stack

Core

Framework - Astro - Static site generation
Language - TypeScript - Type safety
Styling - TailwindCSS - Utility-first CSS
Package Manager - pnpm - Fast, efficient package management

Developer Tools

Linting - ESLint - Code quality
Formatting - Prettier - Code formatting
Git Hooks - Husky - Pre-commit automation
Staged Files - lint-staged - Run linters on staged files

Content & Search

Frontmatter - gray-matter - Parse markdown frontmatter
YAML Processing - yaml - YAML parsing and generation
Search - Pagefind - Static search
Icons - Tabler Icons - Clean SVG icons

CLI & Automation

Interactive Prompts - prompts - CLI user input
Date Management - Custom scripts with Git integration
Post Creation - Interactive and command-line post generation

👨🏻‍💻 Development Setup

Clone and set up the project:

# Clone the repository
git clone https://github.com/your-username/keif.github.io.git
cd keif.github.io

# Install dependencies
pnpm install

# Set up Git hooks
npx husky init

# Start development server
pnpm dev

The blog will be available at http://localhost:4321.

🔧 Configuration

Environment Variables

# .env (optional)
PUBLIC_GOOGLE_SITE_VERIFICATION=your-google-site-verification-value

Date Manager Configuration

Customize the date management system by creating date-manager.config.json:

{
    "contentGlob": "src/data/blog/**/*.{md,mdx}",
    "defaultAuthor": "Your Name",
    "blogDir": "src/data/blog"
}

🧞 Available Commands

Development

Command	Action
pnpm install	Install dependencies
pnpm dev	Start dev server at localhost:4321
pnpm build	Build for production to ./dist/
pnpm preview	Preview production build locally

Blog Management

Command	Action
pnpm new-post	Create a new blog post (interactive)
pnpm new-post "Title" --published --tags "tag1,tag2"	Create post with CLI args
pnpm update-dates	Update dates for changed files
pnpm update-dates:force	Update dates for all posts
pnpm update-dates --dry-run	Preview date changes
pnpm rotate-featured	Randomize featured posts (6 posts)
pnpm rotate-featured:dry-run	Preview featured post rotation

Code Quality

Command	Action
pnpm format:check	Check code format with Prettier
pnpm format	Format code with Prettier
pnpm lint	Lint code with ESLint
pnpm sync	Generate TypeScript types for Astro

🎯 Key Enhancements

This blog setup includes several enhancements over the standard AstroPaper theme:

Automatic Date Management

• Pre-commit hooks automatically update modDatetime when posts are modified
• New posts automatically get pubDatetime set during creation
• ISO 8601 format with milliseconds for precise timestamps
• Cross-platform support (Windows, macOS, Linux)

Featured Post Rotation

• Smart selection combining recent posts with random older content
• Configurable count (default: 6 featured posts)
• Directory exclusions (skips _releases/, examples/ folders)
• Dry-run mode to preview changes before applying

Developer Experience

• Interactive CLI for creating posts with prompts
• Command-line flags for automated post creation
• Dry-run mode to preview changes before applying
• Modern tooling with ESLint, Prettier, Husky, and lint-staged

Workflow Integration

• Git hooks ensure dates are always current
• Lint-staged keeps code clean on commit
• Type safety throughout with TypeScript
• Comprehensive documentation for all features

📜 License

Licensed under the MIT License, Copyright © 2025

---

Built on AstroPaper by Sat Naing 👨🏻‍💻
Enhanced with automatic date management and modern developer tooling.