Stattic - Decentralized Publishing

Stattic is a Python-based static site generator that converts Markdown content into static HTML websites using Jinja2 templates. It supports features such as posts, tags, categories, authors, SEO metadata, image optimization, and asset minification, making it ideal for creating fast, lightweight, and SEO-friendly websites.

Features

• Markdown-based Content: Write your content in Markdown files with YAML frontmatter for metadata.
• Jinja2 Templating: Customize site layouts using Jinja2 templates located in the templates/ directory.
• Pretty Permalinks & Custom URLs: Generate clean URLs with trailing slashes and set custom URLs via frontmatter.
• Tags and Categories: Organize posts with tags and categories, automatically creating archive pages.
• Authors Support: Associate posts with authors loaded from content/authors.yml.
• SEO Support: Add metadata (title, keywords, description) for better SEO.
• Pagination: Control the number of posts per page on the homepage.
• Image Handling: Automatically download external images, convert them to WebP for optimization, and update URLs in content.
• Google Fonts Integration: Download specified Google Fonts and generate corresponding CSS.
• Asset Management: Copy and manage CSS, JS, and font assets, with optional minification.
• RSS Feed and XML Sitemap: Generate RSS feeds and sitemaps for your site when a site URL is provided.
• LLMs.txt for AI Crawlers: Generate structured content files for AI and LLM crawlers to better understand your site.
• 404 Page Generation: Create a custom 404.html page for error handling.
• Logging: Detailed logs of the build process, including performance metrics and errors.
• Error Handling: Gracefully manage template syntax errors, missing files, and download failures.

Table of Contents

1. Installation
2. Usage
3. Content Organization
4. Customization
5. SEO and Metadata
6. Image Optimization
7. Asset Minification
8. RSS Feed and Sitemap
9. LLMs.txt for AI Crawlers
10. Logging
11. Contributing
12. License

---

Installation

Option 1: Install from PyPI (Recommended)

Install Stattic directly from PyPI using pip:

pip install stattic

After installation, you can use the stattic command from anywhere in your terminal.

Option 2: Install from Source

1. Clone the Repository:

   git clone https://github.com/getstattic/stattic.git
   cd stattic
   

2. Install Required Python Dependencies:

   Ensure you have Python 3.8 or higher installed.

   pip install -r requirements.txt
   

3. Install the package in development mode:

   pip install -e .
   

Requirements

Python packages (install via pip)

• markdown: Converts Markdown files to HTML.
• jinja2: Template engine for rendering HTML pages.
• pyyaml: Parses YAML frontmatter from Markdown files.
• requests: Downloads external resources like images and fonts.
• Pillow: Handles image processing and conversion to WebP.
• csscompressor: Minifies CSS files.
• rjsmin: Minifies JavaScript files.
• mistune: Markdown parser with custom rendering.
• watchdog: (Optional) Monitors file changes in watch mode.

---

Usage

Configuration File (Recommended)

Stattic supports configuration files to avoid typing command-line arguments repeatedly. Create a configuration file and complete starter project structure in your project directory:

stattic --init yml

This creates a stattic.yml file with all available settings and sets up your entire project structure including:

• Configuration file: stattic.yml (or .yaml/.json based on your choice)
• Directory structure: templates/, content/posts/, content/pages/, assets/css/, assets/js/, assets/images/
• Template files: All default HTML templates (base.html, post.html, index.html, etc.)
• Sample content: sample-post.md and sample-page.md to get you started
• Configuration files: authors.yml, categories.yml, tags.yml with sample data

The generated stattic.yml contains all available settings:

# Stattic Configuration File
# Configure your static site generator settings here

# Site information
site_url: https://demo.stattic.site
site_title: My Static Site
site_tagline: Built with Stattic

# Build settings
output: output
content: content
templates: templates
assets: assets
blog_slug: blog

# Content settings
posts_per_page: 5
sort_by: date  # date, title, author, order

# Styling
fonts:
  - Quicksand

# SEO settings
robots: public  # public or private
llms: public    # public or private

# Development settings
minify: true
watch: false

After creating your configuration file, simply run:

stattic

Stattic will automatically load settings from:

• stattic.yml or stattic.yaml (YAML format)
• stattic.json (JSON format)

Command-line arguments still work and will override configuration file settings.

Basic Usage

After installation, you can use the stattic command from anywhere in your terminal:

stattic

This command processes the content in the content/ directory, applies the templates from templates/, and outputs the static site to the output/ directory.

Command-Line Arguments

• --output: Specify the output directory. Default is output.

  stattic --output ~/Documents/demo
  

• --content: Specify the content directory. Default is content.

  stattic --content ~/Documents/demo-content
  

• --templates: Specify the templates directory. Default is templates.

  stattic --templates ~/Documents/demo-templates
  

• --assets: Specify the assets directory. Default is assets.

  stattic --assets ~/Documents/demo-assets
  

• --posts-per-page: Number of posts per index (homepage) page. Default is 5.

  stattic --posts-per-page 10
  

• --sort-by: Sort posts by date, title, author or order. Default is date.

  stattic --sort-by title
  

• --fonts: Comma-separated list of Google Fonts to download.

  stattic --fonts "Quicksand, Roboto"
  

• --site-title: Specify the site title for production builds.

  stattic --site-title "Demo title goes here"
  

• --site-tagline: Specify the site tagline for production builds.

  stattic --site-tagline "Demo tagline goes here"
  

• --site-url: Specify the site URL for production builds. Enables RSS feed and sitemap generation.

  stattic --site-url "https://demo.stattic.site"
  

• --robots: Specify if the robots.txt file is public or private. Default is public.

  stattic --robots public
  

• --llms: Specify if the llms.txt file is public or private. Default is public.

  stattic --llms public
  

• --init: Create a sample configuration file and starter project structure. Choose from yml, yaml, or json.

  stattic --init yml
  

  This command creates:

  • Sample configuration file (stattic.yml, stattic.yaml, or stattic.json)
  • Complete directory structure (templates/, content/, assets/)
  • Default template files
  • Sample content files (sample-post.md, sample-page.md)
  • Sample YAML configuration files (authors.yml, categories.yml, tags.yml)

• --watch: (Not Implemented) Enable watch mode to automatically rebuild on file changes.

  stattic --watch
  

• --minify: Minify CSS and JS into single files.

  stattic --minify
  

• --blog-slug: Custom slug for posts instead of 'blog'. Default is blog.

  stattic --blog-slug "articles"
  

• --version: Show the version number.

  stattic --version
  

• --help: Show help message with all available options.

  stattic --help
  

Note: The --watch feature is defined but not yet implemented in the current version.

Example: Building the Site with Custom Fonts and Minification

stattic --output ~/Documents/demo --posts-per-page 10 --sort-by title --fonts "Quicksand, Roboto" --site-url "https://demo.stattic.site" --blog-slug "articles" --llms public --minify

---

Content Organization

Directory Structure

• content/
  • posts/: Place all blog posts here as Markdown (.md) files.
  • pages/: Place all static pages (e.g., About, Contact) here as Markdown (.md) files.
  • categories.yml: Define categories for your posts.
  • tags.yml: Define tags for your posts.
  • authors.yml: Define authors and their details.
• templates/: Contains Jinja2 templates (base.html, post.html, index.html, etc.).
• assets/: Contains CSS, JS, and font files to be copied to the output/assets/ directory.
• output/: The generated static site will be placed here.
• logs/: Build logs are stored here.

Markdown Files with Frontmatter

Each Markdown file should start with a YAML frontmatter block specifying metadata.

Example: Blog Post (content/posts/my-first-post.md)

---
title: "My First Blog Post"
date: 2024-09-25
tags: [Python, Static Sites]
categories: [Technology]
description: "An introduction to Stattic, a simple static site generator."
custom_url: "my-first-post"
author: 1
draft: false
---

# Welcome to Stattic!

This is my first blog post using **Stattic**.

Example: Static Page (content/pages/about.md)

---
title: "About"
custom_url: "about"
description: "Le