Static Blog Template

A production-ready static blog template for GitHub Pages. Built with vanilla JavaScript—no frameworks, no build tools, no dependencies except CDN libraries.

🚀 View Demo | 📖 Documentation | 🐛 Report Bug

Features

• Zero Build Step – Push to GitHub, instantly deployed
• Full-Text Search – Fast search with tag/topic filtering
• Dark Mode – Auto-detection with manual toggle
• Fully Responsive – Optimized for 320px to 2560px
• Accessible – WCAG 2.2 Level AA compliant
• Offline Ready – Works without internet connection
• SEO Optimized – Meta tags, OpenGraph, Schema.org markup

Quick Start

1. Fork this repository
2. Edit config.json with your site details
3. Add posts to posts/ directory (Markdown format)
4. Push to GitHub – Automatic deployment to GitHub Pages

Your blog is live at https://yourusername.github.io

Writing Posts

Create Markdown files in the posts/ directory:

---
title: Your Post Title
date: 2025-01-15
author: Your Name
tags: [javascript, tutorial, web-development]
topic: Web Development
excerpt: A brief description of your post
image: /assets/images/post-image.jpg
---

Your content here using Markdown...

Frontmatter Fields

Field	Required	Description
title	Yes	Post title
date	Yes	Publication date (YYYY-MM-DD)
author	No	Author name (defaults to site author)
tags	No	Array of tags
topic	No	Post category/topic
excerpt	No	Short description
image	No	Featured image URL

Configuration

All site settings are in config.json:

{
  "site": {
    "title": "My Blog",
    "tagline": "Thoughts on code and technology",
    "author": "Your Name",
    "url": "https://yourblog.com",
    "description": "Blog description for SEO"
  },
  "theme": {
    "mode": "auto",
    "colors": {
      "primary": "#007AFF",
      "success": "#34C759",
      "warning": "#FF9F0A"
    }
  },
  "features": {
    "search": true,
    "tags": true,
    "darkMode": true,
    "readingTime": true,
    "relatedPosts": true
  }
}

Configuration Options

Site Settings

• title – Your blog name
• tagline – Subtitle/description
• author – Default author name
• url – Your blog URL (for SEO)
• description – Meta description

Theme

• mode – "light", "dark", or "auto"
• colors – Customize primary colors

Features

Toggle features on/off:

• search – Enable search functionality
• tags – Show post tags
• darkMode – Dark mode toggle
• readingTime – Calculate reading time
• relatedPosts – Show related posts

Project Structure

├── index.html              # Homepage
├── post.html               # Post template  
├── archive.html            # Archive page
├── 404.html                # Error page
├── config.json             # Site configuration
├── app.js                  # Main JavaScript
├── style.css               # Styles
├── posts/                  # Your blog posts
│   └── *.md
├── assets/
│   └── images/             # Images
└── docs/                   # Documentation

Customization

Colors

Edit config.json to change theme colors:

{
  "theme": {
    "colors": {
      "primary": "#007AFF",
      "primaryHover": "#0051D5"
    }
  }
}

Colors use CSS variables. Override in your styles:

:root {
  --color-primary: #007AFF;
  --color-text: #1D1D1F;
}

Typography

CSS variables control typography:

:root {
  --font-family-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-size-base: 16px;
  --line-height-base: 1.6;
}

Layout

Adjust layout widths:

:root {
  --content-width: 1200px;
  --reading-width: 680px;
}

Search

Search supports:

• Full-text search across all posts
• Tag filtering: #javascript
• Topic filtering: @tutorial

Combine filters: #react @tutorial advanced hooks

Dark Mode

Dark mode:

• Auto-detects system preference
• Manual toggle in navigation
• Persists user preference
• Smooth transitions

Accessibility

This template follows WCAG 2.2 Level AA guidelines:

• Semantic HTML structure
• ARIA labels on interactive elements
• Keyboard navigation support
• 44px minimum touch targets
• Color contrast ratios ≥4.5:1
• Screen reader tested

Browser Support

Browser	Version	Support
Chrome	90+	Full
Firefox	88+	Full
Safari	14+	Full
Edge	90+	Full
IE 11	—	Basic (no JS features)

Performance

• Lighthouse score: 95+
• First Contentful Paint: <1s
• Time to Interactive: <2s
• Search latency: <100ms

Deployment

GitHub Pages (Automatic)

1. Enable GitHub Pages in repository settings
2. Set source to main branch
3. Push changes
4. Site updates automatically

Custom Domain

1. Add CNAME file with your domain
2. Configure DNS records with your provider
3. Enable HTTPS in GitHub Pages settings

Development

Local Server

# Python 3
python3 -m http.server 8000

# Node.js
npx http-server

# PHP
php -S localhost:8000

Visit http://localhost:8000

Code Style

• No hardcoded values (use config.json)
• Comments explain why, not what
• Semantic naming conventions
• JSDoc for all functions

License

MIT License - free to use, modify, and distribute.

Credits

Built with:

• Marked.js – Markdown parsing
• Prism.js – Syntax highlighting
• Fuse.js – Fuzzy search

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

---

View Demo • Report Bug • Request Feature