Bun Static Site Generator

A modern, fast static site generator built with Bun and TypeScript. Features a powerful template engine, Markdown processing, and a beautiful design system.

Features

🚀 Ultra-fast generation with Bun runtime
📝 Markdown support with frontmatter metadata
🎨 Modern design system with CSS variables
🏷️ Tag system with automatic tag pages
📱 Responsive design optimized for all devices
🔧 Custom template engine with loops, conditions, and helpers
⚡ Hot reloading during development
📊 Built-in pagination and archive pages
🌐 SEO optimized with proper meta tags

Quick Start

Prerequisites

• Bun installed on your system

Installation

# Clone the repository
git clone https://github.com/yourusername/bun-static-site-generator.git
cd bun-static-site-generator

# Install dependencies
bun install

Basic Usage

# Build the site
bun run build

# Development with hot reload
bun run dev

# Serve the generated site
bun run serve

Project Structure

bun-static-site-generator/
├── content/                    # Markdown content
│   ├── assets/                # Static assets (CSS, images)
│   ├── *.md                   # Blog posts and pages
│   └── a-propos.md           # About page
├── templates/                 # HTML templates
│   ├── partials/              # Reusable template parts
│   │   ├── header.html
│   │   └── footer.html
│   ├── default.html          # Default page template
│   ├── post.html             # Blog post template
│   ├── page.html             # Static page template
│   └── index.html            # Homepage template
├── dist/                      # Generated site (output)
├── src/                       # TypeScript source code
│   ├── types/                # Type definitions
│   ├── utils/                # Utility classes
│   └── generator.ts          # Main generator
└── site.config.js            # Site configuration

Content Creation

Creating Blog Posts

Create Markdown files in the content/ directory with frontmatter:

---
title: "My Blog Post"
description: "A short description"
date: 2024-01-15
author: "Your Name"
tags: ["javascript", "web-development"]
layout: "post"
---

# My Blog Post

Your content here...

Creating Pages

For static pages, use the page layout:

---
title: "About"
description: "About this site"
layout: "page"
---

# About

This is a static page.

Template System

Template Syntax

The template engine supports:

Variables:

{{ page.metadata.title }}          <!-- Escaped HTML -->
{{{ content }}}                     <!-- Unescaped HTML -->

Conditions:

{{ #if page.metadata.tags }}
  <div class="tags">
    <!-- Show tags -->
  </div>
{{ /if }}

Loops:

{{ #each page.metadata.tags }}
  <span class="tag">{{ this }}</span>
{{ /each }}

Helpers:

{{ formatDate page.metadata.date }}
{{ truncate page.metadata.description 120 }}
{{ join page.metadata.tags ", " }}

Available Data

Templates have access to:

• page - Current page data
• site - Site configuration
• pages - All pages array
• content - Processed HTML content
• Custom data passed to specific templates

Configuration

Create a site.config.js file:

export default {
  title: "My Site",
  description: "My awesome static site",
  author: "Your Name",
  baseUrl: "https://mysite.com",
  
  // Directories
  contentDir: "./content",
  templatesDir: "./templates", 
  outputDir: "./dist",
  
  // Templates
  defaultLayout: "default",
  
  // Pagination
  pagination: {
    enabled: true,
    postsPerPage: 10
  }
};

Design System

CSS Variables

The design system uses CSS custom properties:

:root {
  --primary-500: #667eea;
  --gray-900: #18181b;
  --space-4: 1rem;
  --text-lg: 1.125rem;
  --radius-md: 0.5rem;
}

Component Classes

• .container - Max-width container
• .post-card - Blog post card
• .article-header - Article header
• .tag - Tag styling
• .hero - Hero section

Development

Scripts

# Development with watch mode
bun run dev

# Build for production
bun run build

# Serve built site
bun run serve

# Clean build directory
bun run clean

File Structure

• Generator (src/generator.ts) - Main site generation logic
• Templates (src/utils/templating.ts) - Template engine
• Markdown (src/utils/markdown.ts) - Markdown processing
• FileSystem (src/utils/fileSystem.ts) - File operations

Advanced Features

Tag Pages

Automatically generates pages for each tag at /tags/{tag}.html

Pagination

Configure pagination in site.config.js:

pagination: {
  enabled: true,
  postsPerPage: 5
}

Related Posts

Automatically finds related posts based on shared tags.

Table of Contents

Auto-generated TOC for long articles:

<!-- In templates -->
{{{ toc }}}

Deployment

Build for Production

bun run build

The generated site will be in the dist/ directory, ready for deployment to any static hosting service.

Hosting Options

• Netlify - Drop the dist folder
• Vercel - Connect your repository
• GitHub Pages - Push dist to gh-pages branch
• Any static host - Upload dist contents

Customization

Adding Custom Helpers

Extend the template engine in src/utils/templating.ts:

// Add to processHelpers method
case 'customHelper': {
  const input = String(args[0] || '');
  return input.toUpperCase();
}

Custom Layouts

Create new templates in templates/ and reference them in frontmatter:

---
layout: "custom"
---

Styling

Modify content/assets/style.css or add your own CSS files.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Markdown processing with frontmatter
• Template engine with loops and conditions
• Modern design system
• Tag system and pagination
• Development server with hot reload

---

Built with ❤️ using Bun