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.
- 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.htmlpage 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.
- Installation
- Usage
- Content Organization
- Customization
- SEO and Metadata
- Image Optimization
- Asset Minification
- RSS Feed and Sitemap
- LLMs.txt for AI Crawlers
- Logging
- Contributing
- License
Install Stattic directly from PyPI using pip:
pip install statticAfter installation, you can use the stattic command from anywhere in your terminal.
-
Clone the Repository:
git clone https://github.com/getstattic/stattic.git cd stattic -
Install Required Python Dependencies:
Ensure you have Python 3.8 or higher installed.
pip install -r requirements.txt
-
Install the package in development mode:
pip install -e .
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.
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 ymlThis creates a stattic.yml file with all available settings and sets up your entire project structure including:
- Configuration file:
stattic.yml(or.yaml/.jsonbased 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.mdandsample-page.mdto get you started - Configuration files:
authors.yml,categories.yml,tags.ymlwith 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: falseAfter creating your configuration file, simply run:
statticStattic will automatically load settings from:
stattic.ymlorstattic.yaml(YAML format)stattic.json(JSON format)
Command-line arguments still work and will override configuration file settings.
After installation, you can use the stattic command from anywhere in your terminal:
statticThis command processes the content in the content/ directory, applies the templates from templates/, and outputs the static site to the output/ directory.
-
--output: Specify the output directory. Default isoutput.stattic --output ~/Documents/demo -
--content: Specify the content directory. Default iscontent.stattic --content ~/Documents/demo-content -
--templates: Specify the templates directory. Default istemplates.stattic --templates ~/Documents/demo-templates -
--assets: Specify the assets directory. Default isassets.stattic --assets ~/Documents/demo-assets -
--posts-per-page: Number of posts per index (homepage) page. Default is5.stattic --posts-per-page 10
-
--sort-by: Sort posts bydate,title,authorororder. Default isdate.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 ispublic.stattic --robots public
-
--llms: Specify if the llms.txt file is public or private. Default ispublic.stattic --llms public
-
--init: Create a sample configuration file and starter project structure. Choose fromyml,yaml, orjson.stattic --init yml
This command creates:
- Sample configuration file (
stattic.yml,stattic.yaml, orstattic.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)
- Sample configuration file (
-
--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 isblog.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.
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 --minifycontent/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 theoutput/assets/directory.output/: The generated static site will be placed here.logs/: Build logs are stored here.
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: "Learn more about Stattic and its features."
author: 1
nav_hide: false
---
# About Stattic
Stattic is a Python-based static site generator...
Customize your site's layout by editing Jinja2 templates in the templates/ directory.
base.html: The global layout for all pages. Includes header, footer, and asset links.post.html: Template for individual blog posts.index.html: The main homepage template listing recent posts.404.html: Custom 404 error page.
You can create additional templates for specific layouts or sections by following the naming conventions and extending base.html.
Enhance your site's SEO by adding metadata in the frontmatter of your Markdown files.
title: The title of the page or post.description: A brief description for SEO purposes.keywords: Relevant keywords for the page or post.author: The author ID as defined inauthors.yml.custom_url: Custom URL slug for the page or post.canonical: The canonical URL for the page or post.
Example:
---
title: "SEO Optimization with Stattic"
description: "Learn how to optimize your static site for search engines."
keywords: [SEO, Static Site, Optimization]
custom_url: "seo-optimization"
canonical: "https://yourdomain.com/custom-url"
author: 2
---
Stattic automatically handles image optimization by:
- Downloading External Images: Images referenced via URLs in your content are downloaded and stored locally in the
output/images/directory. - Converting to WebP: Downloaded images are converted to WebP format for better performance.
- Updating Image URLs: Image references in your content are updated to point to the optimized WebP versions.
Example:
After processing, the above will be converted to:
<img src="images/logo.webp" alt="Logo">
Improve your site's performance by minifying CSS and JavaScript assets.
- Enable Minification: Use the
--minifyflag when runningstattic.py.
python3 stattic.py --minify
-
Minified Files:
output/assets/css/main.min.css: Combined and minified CSS.output/assets/js/main.min.js: Combined and minified JavaScript.
Note: Ensure that your templates reference these minified files when the --minify flag is used.
Generate an RSS feed and XML sitemap for your site by providing the --site-url argument.
-
Generate RSS Feed and Sitemap:
python3 stattic.py --site-url "https://demo.stattic.site" -
Generated Files:
output/feed/index.xml: RSS feed containing your latest posts.output/sitemap.xml: XML sitemap listing all pages and posts.
Note: RSS and sitemap generation are only enabled when a valid --site-url is provided.
Generate an llms.txt file that provides structured content for AI crawlers and Large Language Models (LLMs). This file helps AI systems understand and index your site's content more effectively.
-
Generate LLMs.txt:
stattic --site-url "https://demo.stattic.site" --llms public -
Disable LLMs.txt Generation:
stattic --llms private
-
Generated File:
output/llms.txt: Structured content listing with posts, pages, and site information formatted for LLM consumption.
File Content Includes:
- Site title and description
- List of all blog posts with titles, URLs, and unique IDs
- List of all pages with titles, URLs, and unique IDs
- Sitemap reference for comprehensive site structure
Example llms.txt Content:
# My Static Site - a Python-based static site generator's demo website
This site contains structured content formatted for LLM-friendly consumption.
## Posts
- [Welcome to Your New Static Site](https://demo.stattic.site/blog/sample-post/): ID 3851798142
## Pages
- [About This Site](https://demo.stattic.site/sample-page/): ID 4646506025
## Sitemap
https://demo.stattic.site/sitemap.xml
Note: LLMs.txt generation is enabled by default (--llms public) when a valid --site-url is provided. Use --llms private to disable it for development or private sites.
Stattic provides detailed logs of the build process, including performance metrics and errors.
- Log Files: Stored in the
logs/directory with timestamps.
Example Log Entry:
2024-09-27 12:34:56 - INFO - Starting build process...
2024-09-27 12:34:56 - INFO - Created output directory: output
2024-09-27 12:34:57 - INFO - Loaded 3 categories and 5 tags
2024-09-27 12:34:57 - INFO - Converted Markdown to HTML using Mistune (Time taken: 0.45 seconds)
2024-09-27 12:34:58 - INFO - Generated post: output/blog/my-first-post/index.html
2024-09-27 12:34:59 - INFO - Generated index page: output/index.html
2024-09-27 12:34:59 - INFO - Site build completed successfully in 3.00 seconds.
- Console Output: Also displays INFO level logs for real-time feedback.
We welcome contributions! To contribute:
- Fork the Repository:
git clone git@github.com:getstattic/stattic.git
cd stattic
- Create a New Branch:
git checkout -b feature-branch
-
Make Your Changes: Implement your features or fixes.
-
Commit Your Changes:
git commit -m "Add feature XYZ"
- Push to Your Fork:
git push origin feature-branch
- Submit a Pull Request: Open a pull request detailing your changes.
This project is licensed under the MIT License. See the LICENSE file for details.