LightStaticSite

A powerful, modular, and fast static site generator in Python, developed specifically for this blog. Supports incremental builds, image optimization, and SEO out of the box.

Key Features

🚀 Incremental Build

The generator tracks file changes using the SHA-256 algorithm. If the article content or templates haven't changed, the page is not rebuilt. Includes support for cache versioning and automatic cleanup of outdated entries.

🖼️ Automatic Image Optimization

WebP Conversion: Automatic conversion to modern format to save traffic.
Smart Resize: Limit width to 1600px for faster loading.
Lazy Loading: Automatic addition of loading="lazy" to all images.

📝 Drafts Support

Just add draft: true to the article's front-matter metadata, and it will be ignored during the site build.

🔍 Built-in SEO and Localization

Sitemap / RSS / Robots: Automatic generation of all files necessary for search engines.
Multilingualism: Support for the lang field for automatic interface switching (navbar, footer).
Structured Logging: Replaces plain prints with the logging module with timestamps.

📤 Smart Sharing

Native Share API: Use the system "Share" menu on mobile devices.
Improved Copying: "Copy link" button based on Clipboard API with a reliable fallback.
Clean Titles: Eliminates HTML entities (like &) when reposting to social networks.

Project Architecture

The code is divided into specialized modules: build.py, build_config.py, build_cache.py, build_parser.py, build_image.py, build_seo.py, and build_utils.py.

Workflow Diagram

graph TD A[Markdown Files] --> B[build.py] C[Templates] --> B D[.build_cache.json] <--> B B --> E[HTML Pages] B --> F[Sitemap / RSS] B --> G[Images / Assets] B --> B1 subgraph "Phase 1: Analysis" B1[Check Hash Changes] B2[Parse Metadata] end subgraph "Phase 2: Processing" B3[Slug Translation] B4[Image Optimization] B5[Markdown to HTML] end subgraph "Phase 3: Generation" B6[SEO Elements] B7[Cleanup Old Files] end B2 --> B3 B5 --> B6

How to Use

Requirements: Python 3.x, dependencies (markdown, Pillow, beautifulsoup4, transliterate).

Build site: ./gen.sh or python3 build.py

Front-matter Metadata:

---
title: Article Title
date: 2026-01-09
tags: AI, Python, Web
description: Brief description for SEO
image: cover.png # converted to .webp
slug: custom-path
lang: en # or ru
aliases: old-post-name, test-path
draft: false
---

Troubleshooting

Problem	Solution
Templates not updating	Delete `.build_cache.json`.
Optimization error	`Pillow` is required, otherwise images are just copied.
Slugs in wrong language	Internet required for translation API, otherwise transliteration is used.