Val Town Blog

The Val Town Blog is now hosted directly on Val Town! The blog combines new posts written directly in this project with proxied content from our legacy blog.

The blog includes a comprehensive dark mode implementation:

• Automatic theme detection: Respects the user's system preference (prefers-color-scheme)
• Manual toggle: Users can manually switch between light and dark themes using the toggle button in the header
• Persistent preference: Theme choice is saved in localStorage and persists across sessions
• Smooth transitions: All theme changes include smooth CSS transitions
• Syntax highlighting: Code blocks automatically switch between light and dark syntax highlighting themes

The dark mode uses carefully selected colors that maintain readability and accessibility while providing a comfortable viewing experience in low-light conditions.

• New Posts: Blog posts are written in markdown with YAML frontmatter and stored in the /posts directory
• Legacy Posts: Older blog posts are proxied from the original blog hosted at Cloudflare Pages (val-town-blog.pages.dev)
• Homepage: The homepage dynamically displays posts by:
  1. Reading local markdown files from the /posts directory
  2. Combining them with posts from the old blog
  3. Sorting all posts by date
  4. Rendering the content with a clean, custom design

• /index.ts: Main entry point that sets up Hono routing and middleware
• /components/: React components for rendering the blog
  • Layout.tsx: Shared layout with header, footer, and styling
  • HomePage.tsx: Renders the blog homepage with featured and recent posts
  • BlogPost.tsx: Renders individual blog posts
  • Head.tsx: Manages metadata, styles, and SEO
• /routes/: Hono route handlers for different parts of the blog
  • home.ts: Homepage route
  • blog.ts: Individual blog post routes
  • proxy.ts: Proxy to the old blog for legacy content
  • rss.ts: RSS feed generation
  • favicon.ts & og-image.ts: Asset routes
• /utils/: Utility functions for post processing, caching, etc.
• /posts/: Markdown files for blog posts
• /styles/: CSS styling

• React: For server-side rendering components
• Hono: Lightweight web framework for routing
• Custom CSS: For styling with CSS custom properties for theming
• Dark Mode: CSS custom properties with data-theme attribute switching
• Unified/Remark/Rehype: For markdown processing with GitHub Flavored Markdown support
• Gray Matter: For parsing YAML frontmatter

To add a new blog post to the Val Town Blog:

1. Create a markdown file in the /posts directory with YAML frontmatter:

---
title: My New Blog Post
description: A brief description of the post
pubDate: 2025-04-01T00:00:00.000Z
author: Your Name
---

Content of your blog post in markdown format...

2. The post will automatically appear on the homepage and be accessible at /blog/[slug]

The blog supports GitHub Flavored Markdown (GFM) with:

• Code syntax highlighting
• Tables
• Lists
• Images
• And other standard markdown features

The dark mode system uses several key components:

1. CSS Custom Properties: All colors are defined as CSS variables in :root for light mode and [data-theme="dark"] for dark mode
2. System Preference Detection: Uses @media (prefers-color-scheme: dark) to automatically apply dark mode for users who prefer it
3. Theme Toggle Component: A React component (ThemeToggle.tsx) that renders the toggle button and includes the JavaScript for theme switching
4. Persistent Storage: Theme preference is saved to localStorage and restored on page load
5. Syntax Highlighting: Different highlight.js themes are loaded for light and dark modes using media queries

The implementation prevents flash of unstyled content (FOUC) by applying the theme immediately in an inline script before the page renders.

The blog includes a live reload feature that automatically refreshes the page when changes are made to the project. This works when viewing the blog on a .val.run domain during development.

The blog implements efficient caching:

• Cache headers are set for Cloudflare CDN but not for browsers
• Cache TTL is set to 5 minutes by default
• Domains ending with .val.run are excluded from caching

• Server-side rendering for fast initial page loads
• Efficient proxy for legacy content
• Minimal CSS with no external frameworks
• Optimized image handling

The blog is deployed directly on Val Town, with the production version available at blog.val.town.