bahdotsh / blogr

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:** **For a personal website instead of a blog:** Installation **Requirements:** • Rust 1.70+ (Install Rust) • Git (for deployment) • GitHub account (for GitHub Pages deployment) **Install from crates.io (recommended):** **Install from source:** 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 **Site Generation** • Fast static site builds • Multiple themes: 7 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** **Content Management** **Development & Deployment** **Configuration** Project Structure When you create a new blog, Blogr generates this structure: **Key files:** • - Your site configuration • - All your blog posts in Markdown • - Images, custom CSS, and JavaScript files • - Automatic deployment setup Configuration Edit to configure your site. Use for an interactive editor. **Basic Configuration:** For detailed configuration options, see the Configuration Guide. Post Format Posts use Markdown with YAML frontmatter: **Frontmatter Fields:** • - Post title (required) • - Publication date (auto-generated if not provided) • - Author name (uses blog author if not provided) • - Post description for SEO • - Array of tags for categorization • - or • - URL slug (auto-generated from title if not provided) Personal Website Content For personal mode ( ), use 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 : Use standard LaTeX delimiters in your Markdown: • **Inline math**: renders as inline math • **Display math**: renders as a centered block equation Blogr's markdown parser converts to and to , which MathJax then renders client-side. Themes Blogr comes with 7 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)** • Set up GitHub token: Get a token at https://github.com/settings/tokens (needs and scopes) • Deploy: Your blog will be available at **Custom Domains** • Configure domain: • Set up DNS records (A records for apex domains, CNAME for s…