Blogr

A fast, lightweight static site generator built in Rust for creating and managing blogs. Write in Markdown, preview with a built-in terminal editor, and deploy to GitHub Pages with a single command.

Quick Start

Get up and running in 5 minutes:

# 1. Install Blogr
cargo install blogr-cli

# 2. Create your blog
blogr init my-blog
cd my-blog

# 3. Create your first post
blogr new "Hello World"

# 4. Preview your blog
blogr serve
# Opens http://localhost:3000

# 5. Deploy to GitHub Pages
export GITHUB_TOKEN=your_github_token
blogr deploy

For a personal website instead of a blog:

blogr init --personal my-portfolio

Installation

Requirements:

• Rust 1.70+ (Install Rust)
• Git (for deployment)
• GitHub account (for GitHub Pages deployment)

Install from crates.io (recommended):

cargo install blogr-cli

Install from source:

git clone https://github.com/bahdotsh/blogr.git
cd blogr
cargo install --path blogr-cli

Features

Two Site Types

• Blog Mode: Traditional blog with posts, archives, tags, and RSS feeds
• Personal Mode: Portfolio/personal website without blog functionality
• Single command initialization for either type
• Theme-specific optimizations for each mode

Content Creation

• Write posts in Markdown with YAML frontmatter
• Built-in terminal editor with live preview
• Draft and published post management
• Tag-based organization
• Automatic slug generation
• External post support (link to posts hosted elsewhere)

Site Generation

• Fast static site builds
• Multiple themes: 8 built-in themes for blogs and personal sites
• Full-text search with MiniSearch integration
• Syntax highlighting for code blocks
• MathJax support for LaTeX math expressions (opt-in)
• RSS/Atom feeds (blog mode)
• SEO-friendly output

Development

• Live reload development server
• Interactive configuration editor
• Project validation and cleanup tools
• Comprehensive CLI commands

Deployment

• One-command GitHub Pages deployment
• Custom domain support with CNAME generation
• Automatic git branch management
• Deployment status checking

Newsletter System (optional)

• Email subscription collection via IMAP
• Interactive subscriber approval interface
• Newsletter creation from blog posts or custom content
• SMTP integration for reliable email delivery
• Import/export from popular services (Mailchimp, ConvertKit, etc.)
• REST API for external integrations
• Extensible plugin system

Documentation

For detailed information about specific features, see the following documentation:

• Commands Reference - Complete CLI command reference
• Configuration Guide - All configuration options
• Themes Guide - Available themes and customization
• Newsletter System - Email newsletter setup and usage
• Search Feature - Full-text search configuration
• Terminal Editor - Built-in editor usage

Basic Commands

Project Management

blogr init my-blog                    # Create new blog
blogr init --personal my-portfolio   # Create personal website
blogr project info                    # Show project details

Content Management

blogr new "My Post Title"             # Create new post
blogr list                            # List all posts
blogr edit my-post-slug               # Edit existing post

Development & Deployment

blogr serve                           # Start dev server
blogr build                           # Build static site
blogr deploy                          # Deploy to GitHub Pages

Configuration

blogr config edit                     # Interactive config editor
blogr theme set minimal-retro         # Switch theme

Project Structure

When you create a new blog, Blogr generates this structure:

my-blog/
├── blogr.toml              # Configuration file
├── posts/                  # Markdown posts
│   ├── welcome.md          # Sample post
│   └── about.md            # About page
├── static/                 # Static files (images, CSS, JS)
│   ├── images/
│   ├── css/
│   └── js/
└── .github/workflows/      # GitHub Actions (auto-generated)
    └── deploy.yml

Key files:

• blogr.toml - Your site configuration
• posts/ - All your blog posts in Markdown
• static/ - Images, custom CSS, and JavaScript files
• .github/workflows/ - Automatic deployment setup

Configuration

Edit blogr.toml to configure your site. Use blogr config edit for an interactive editor.

Basic Configuration:

[blog]
title = "My Blog"
author = "Your Name"
description = "My thoughts and ideas"
base_url = "https://yourusername.github.io/blog"

[theme]
name = "minimal-retro"  # or "dark-minimal" for personal sites

[github]
username = "yourusername"
repository = "blog"

[site]
site_type = "blog"  # or "personal" for portfolio sites

[math]
enabled = true  # Enable MathJax for LaTeX math rendering

For detailed configuration options, see the Configuration Guide.

Post Format

Posts use Markdown with YAML frontmatter:

---
title: "My Blog Post"
date: "2024-01-15"
author: "Your Name"
description: "Brief description"
tags: ["rust", "programming"]
status: "published"
slug: "my-blog-post"
---

# My Blog Post

Your content goes here in **Markdown**.

Frontmatter Fields:

• title - Post title (required)
• date - Publication date (auto-generated if not provided)
• author - Author name (uses blog author if not provided)
• description - Post description for SEO
• tags - Array of tags for categorization
• status - "published" or "draft"
• slug - URL slug (auto-generated from title if not provided)
• featured - Boolean, mark post as featured (default: false)
• external_url - URL for external posts (appears in listings but links externally)

Personal Website Content

For personal mode (--personal), use content.md with frontmatter to define your site. See the Themes Guide for detailed examples.

Search

Blogr includes a powerful client-side full-text search feature powered by MiniSearch. Search is enabled by default and works entirely in the browser without requiring a server.

Features:

• Full-text search across post titles, tags, and content
• Real-time results as you type
• Keyboard navigation (use / to focus search)
• Smart excerpts with highlighted search terms
• Lazy loading for better performance

For detailed search configuration and troubleshooting, see the Search Feature Guide.

Math Support

Blogr supports LaTeX math expressions via MathJax 3. Math rendering is opt-in — add the following to your blogr.toml:

[math]
enabled = true

Use standard LaTeX delimiters in your Markdown:

• Inline math: $E = mc^{2}$ renders as inline math
• Display math: $$\sum_{i=1}^{n} i$$ renders as a centered block equation

Blogr's markdown parser converts $...$ to \(...\) and $$...$$ to \[...\], which MathJax then renders client-side.

Themes

Blogr comes with 8 built-in themes designed for different purposes:

Blog Themes:

• Minimal Retro (default) - Clean, artistic design with retro aesthetics
• Obsidian - Compatible with Obsidian community themes
• Terminal Candy - Quirky terminal-inspired theme with pastel colors
• Brutja - Minimal, brutalist theme with pops of color

Personal Website Themes:

• Dark Minimal (default) - Dark minimalist-maximalist with cyberpunk aesthetics
• Musashi - Dynamic modern theme with smooth animations
• Slate Portfolio - Glassmorphic professional portfolio theme
• Typewriter - Vintage typewriter aesthetics with nostalgic charm

For detailed theme information, customization options, and setup instructions, see the Themes Guide.

Newsletter System

Blogr includes a comprehensive email newsletter system that allows you to collect subscribers, manage them through an approval interface, and send newsletters based on your blog posts or custom content.

Features:

• Email subscription collection via IMAP
• Interactive approval interface for subscriber requests
• Automatic newsletters from latest blog posts
• Custom newsletter creation with Markdown content
• SMTP integration for reliable email delivery
• Import/export from popular services (Mailchimp, ConvertKit, etc.)
• REST API for external integrations
• Extensible plugin system

For detailed newsletter setup, configuration, and usage, see the Newsletter System Guide.

Deployment

GitHub Pages (recommended)

1. Set up GitHub token:

   export GITHUB_TOKEN=your_token
   

   Get a token at https://github.com/settings/tokens (needs repo and workflow scopes)

2. Deploy:

   blogr deploy
   

Your blog will be available at https://yourusername.github.io/repository

Custom Domains

1. Configure domain: blogr config domain set yourdomain.com
2. Set up DNS records (A records for apex domains, CNAME for subdomains)
3. Deploy and configure in GitHub repository Settings → Pages → Custom domain

Manual Deployment

blogr build
# Copy contents of `dist/` folder to your web server

Development

Build from source:

git clone https://github.com/bahdotsh/blogr.git
cd blogr
cargo build --release

Run tests:

cargo test

Code structure:

• blogr-cli/ - Main CLI application
• blogr-themes/ - Theme system

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Areas to help:

• New themes
• Features and bug fixes
• Documentation
• Testing

Changelog

v0.4.1 (Latest)

New Features:

• External Post Support: Create posts that link to external URLs, appearing in listings but redirecting to the original source
• Search Improvements: Insert spaces at block boundaries in plain text extraction for better search indexing
• Newsletter API: API endpoints for creating and sending newsletters
• Newsletter Hardening: Cleanup, rate limiting, and validation improvements for the newsletter subsystem

v0.4.0

New Features:

• Typewriter Theme: Vintage typewriter-inspired theme for personal websites with nostalgic aesthetics
• Brutja Theme: Minimal brutalist blog theme with pops of color
• Blog Link Support: All personal website themes now support a blog link in social links
• Content.md Override: Personal mode now uses title and description from content.md instead of blogr.toml
• Conditional Separators: Typewriter theme displays separator lines only when sections are present

Improvements:

• Better theme organization with clear separation between blog and personal themes
• Enhanced personal website customization options
• Improved documentation for all themes

Themes:

• Blog themes: Minimal Retro, Obsidian, Terminal Candy, Brutja
• Personal themes: Dark Minimal, Musashi, Slate Portfolio, Typewriter

Previous Versions

See blogr-themes/README.md for detailed theme changelog.

License

MIT License - see LICENSE for details.

Links

• Issues
• Contributing

---

Built with Rust 🦀