A powerful static site generator that combines Markdown content with Jinja2 templating and database-driven page generation. Presskit lets you build dynamic static sites by connecting your content to SQLite databases and JSON data sources.
pip install presskit
Or you can use Astral's uv Python package manager to install Presskit as a self-contained tool so it can be run from the command line without needing to activate a virtual environment:
uv tool install presskit
Presskit supports different data sources. Install additional dependencies based on your needs:
# For PostgreSQL support
pip install presskit[postgresql]
# For DuckDB support
pip install presskit[duckdb]
mkdir my-site
cd my-site
presskit init
This creates the basic structure and sample files:
my-site/
├── presskit.json # Configuration file
├── content/ # Markdown files
│ └── index.md # Sample homepage
├── templates/ # HTML templates
│ ├── base.html # Base template
│ └── page.html # Page template
├── static/ # Static assets (CSS, JS, images)
└── public/ # Generated output (created automatically)
presskit build
Create Markdown files in the content/ directory. Each file can include YAML front matter for metadata:
---
title: "Welcome to My Site"
description: "A brief introduction"
layout: page
---
# Welcome
This is my **awesome** site built with Presskit!
HTML files also support YAML frontmatter:
---
title: "My HTML Page"
description: "A page with frontmatter"
layout: custom
---
<div class="content">
<h1>{{ title }}</h1>
<p>{{ description }}</p>
</div>
Templates go in the templates/ directory. Here's a basic page.html template:
<!DOCTYPE html>
<html lang="{{ site.language }}">
<head>
<meta charset="UTF-8">
<title>{{ page.title or site.title }}</title>
<meta name="description" content="{{ page.description or site.description }}">
</head>
<body>
<header>
<h1>{{ site.title }}</h1>
</header>
<main>
{{ page.content }}
</main>
<footer>
<p>© {{ build.year }} {{ site.author }}</p>
</footer>
</body>
</html>
Create a presskit.json file to configure your site:
{
"title": "My Awesome Site",
"description": "A site built with Presskit",
"author": "Your Name",
"url": "https://mysite.com",
"language": "en-US"
}
Presskit provides a structured context with the following variables available in all templates:
site.*)site.title - Site titlesite.description - Site descriptionsite.author - Site authorsite.url - Base site URLsite.version - Site versionsite.language - Site languagebuild.*)build.date - Build date (YYYY-MM-DD)build.year - Build yearbuild.timestamp - Full build timestampbuild.iso_date - Build date in ISO formatpage.*)page.filename - Page filename without extensionpage.filepath - Full file pathpage.path - Clean URL pathpage.layout - Template layout namepage.content - Processed HTML content (in templates)page.title - Page title from front matterpage.description - Page description from front matterdata.*)data.queries - Results from named queriesdata.sources - JSON data sourcesdata.page_queries - Page-specific query resultsPlus any custom variables from your front matter are available at the top level.
Presskit includes comprehensive static asset management for CSS, JavaScript, images, fonts, and other static files. Assets are automatically copied from your static/ directory to the output directory during builds, with smart incremental copying in watch mode.
Add a static/ directory to your project for all static assets:
my-site/
├── presskit.json
├── content/
├── templates/
├── static/ # Static assets directory
│ ├── css/
│ │ ├── main.css
│ │ └── theme.css
│ ├── js/
│ │ ├── app.js
│ │ └── vendor.js
│ ├── images/
│ │ ├── logo.png
│ │ └── hero.jpg
│ └── fonts/
│ └── custom-font.woff2
└── public/ # Generated output
├── css/ # Assets copied here
├── js/
├── images/
└── fonts/
During builds, all files in static/ are copied to the root of your output directory:
static/css/main.css → public/css/main.cssstatic/images/logo.png → public/images/logo.pngstatic/js/app.js → public/js/app.jsDuring watch mode (--reload), only changed assets are copied for faster builds.
Asset management can be configured in your presskit.json:
{
"static_dir": "static",
"assets": {
"include_patterns": ["**/*"],
"exclude_patterns": [".DS_Store", "*.tmp", "*.swp", "Thumbs.db"],
"clean_destination": false
}
}
static_dir (default: "static") - Directory containing static assetsassets.include_patterns (default: ["**/*"]) - Glob patterns for files to copyassets.exclude_patterns - Patterns to exclude from copyingassets.clean_destination (default: false) - Remove orphaned files from previous builds{
"static_dir": "assets",
"assets": {
"include_patterns": ["*.css", "*.js", "images/**/*", "fonts/**/*"],
"exclude_patterns": [
".DS_Store",
"*.tmp",
"*.swp",
"*.backup",
"node_modules/**/*"
],
"clean_destination": true
}
}
Reference your static assets in templates using standard paths:
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title or site.title }}</title>
<!-- CSS assets -->
<link rel="stylesheet" href="/css/main.css">
<link rel="stylesheet" href="/css/theme.css">
</head>
<body>
<header>
<img src="/images/logo.png" alt="{{ site.title }}">
<h1>{{ site.title }}</h1>
</header>
<main>
{{ page.content }}
</main>
<!-- JavaScript assets -->
<script src="/js/vendor.js"></script>
<script src="/js/app.js"></script>
</body>
</html>
static/
├── css/
├── js/
├── images/
├── fonts/
└── downloads/
static/
├── home/
│ ├── hero.jpg
│ └── home.css
├── blog/
│ ├── post.css
│ └── syntax.css
└── shared/
├── common.css
└── logo.png
When using presskit build --reload or presskit server --reload, the static directory is automatically watched for changes:
# Watches content/, templates/, static/, and data/ directories
presskit build --reload
Changes to static assets trigger:
Control which files are copied with glob patterns:
{
"assets": {
"include_patterns": [
"**/*.css", // All CSS files
"**/*.js", // All JavaScript files
"images/**/*.{png,jpg,gif,svg}", // Specific image types
"fonts/**/*.{woff,woff2,ttf}", // Font files
"downloads/**/*" // Everything in downloads
],
"exclude_patterns": [
"**/*.scss", // Ignore Sass source files
"**/*.ts", // Ignore TypeScript source
"**/node_modules/**", // Ignore dependencies
"**/.git/**", // Ignore version control
"**/*~", // Ignore backup files
"**/Thumbs.db" // Ignore system files
]
}
}
Assets are copied before content processing, ensuring they're available when templates reference them:
You can use a different directory name for your static assets:
{
"static_dir": "assets"
}
my-site/
├── presskit.json
├── content/
├── templates/
├── assets/ # Custom static directory name
│ ├── styles/
│ ├── scripts/
│ └── media/
└── public/
Static directory paths support environment variables:
{
"static_dir": "${ASSETS_DIR}/static"
}
During builds, Presskit reports asset copying progress:
$ presskit build
Copying static assets...
Copied 45 assets successfully
Building...
Found 12 files to process
Build complete!
For large asset directories:
Copying static assets...
Copying assets: 127/150 (84.7%)
Copied 148 assets successfully, 2 failed
- Failed: images/corrupted.jpg (Permission denied)
- Failed: large-file.zip (Disk full)
You can use Jinja2 templating directly in your Markdown content:
---
title: About
category: personal
---
# About {{ site.author }}
This site was built on {{ build.date }} and is currently version {{ site.version }}.
{% if category == "personal" %}
This is a personal page about {{ site.author }}.
{% endif %}
Presskit's data integration feature allows you to connect your static site to data sources, enabling content generation while maintaining the performance benefits of static sites. This powerful feature bridges the gap between static and dynamic websites.
This enables data-driven pages that display statistics, reports, or any structured data. Ideal for portfolios showcasing project metrics, business dashboards, or documentation sites pulling from APIs.
This encourages separation of concerns where you keep your content in databases where it can be easily edited, queried, and managed, while your site structure remains in version control.
Presskit supports multiple data source types. Add them to your presskit.json:
{
"sources": {
"blog_db": {
"type": "sqlite",
"path": "data/blog.db"
}
}
}
{
"sources": {
"postgres_db": {
"type": "postgresql",
"host": "localhost",
"port": 5432,
"database": "mydb",
"username": "user",
"password": "${DB_PASSWORD}"
}
}
}
{
"sources": {
"analytics_db": {
"type": "duckdb",
"path": "data/analytics.duckdb"
}
}
}
{
"sources": {
"config": {
"type": "json",
"path": "data/site-config.json"
}
}
}
JSON sources support both basic data loading and advanced JSONPath querying for extracting specific data from complex JSON structures.
You can also use connection strings for database sources:
{
"sources": {
"prod_db": {
"type": "postgresql",
"connection_string": "${DATABASE_URL}"
}
}
}
JSON sources support powerful JSONPath expressions for extracting data from complex JSON structures. JSONPath is a query language for JSON, similar to XPath for XML.
Given a JSON file data/users.json:
{
"users": [
{"id": 1, "name": "Alice", "role": "admin", "posts": 25},
{"id": 2, "name": "Bob", "role": "editor", "posts": 12},
{"id": 3, "name": "Carol", "role": "admin", "posts": 8}
],
"settings": {
"theme": "dark",
"features": ["comments", "analytics"]
}
}
You can query this data using JSONPath expressions:
{
"sources": {
"users_data": {
"type": "json",
"path": "data/users.json"
}
},
"queries": [
{
"name": "all_users",
"source": "users_data",
"query": "$.users[*]"
},
{
"name": "admin_users",
"source": "users_data",
"query": "$.users[?(@.role == 'admin')]"
},
{
"name": "user_names",
"source": "users_data",
"query": "$.users[*].name"
},
{
"name": "active_users",
"source": "users_data",
"query": "$.users[?(@.posts > 10)]"
}
]
}
$ - Root element. - Child element[*] - All array elements[0] - First array element[?(@.field == 'value')] - Filter expression..field - Recursive descent (find field anywhere)[start:end] - Array sliceFor basic access, you can also use simple dot notation:
{
"name": "theme_setting",
"source": "users_data",
"query": "settings.theme"
}
Define queries to load data from your sources:
{
"sources": {
"blog_db": {
"type": "sqlite",
"path": "data/blog.db"
}
},
"queries": [
{
"name": "recent_posts",
"source": "blog_db",
"query": "SELECT title, slug, date, excerpt FROM posts ORDER BY date DESC LIMIT 5"
},
{
"name": "categories",
"source": "blog_db",
"query": "SELECT name, slug, COUNT(*) as post_count FROM categories JOIN posts ON categories.id = posts.category_id GROUP BY categories.id"
}
]
}
Access query results through the data.queries object. This works for both SQL and JSON query results:
<section class="recent-posts">
<h2>Recent Posts</h2>
{% for post in data.queries.recent_posts %}
<article>
<h3><a href="/posts/{{ post.slug }}">{{ post.title }}</a></h3>
<time>{{ post.date | date_format('%B %d, %Y') }}</time>
<p>{{ post.excerpt }}</p>
</article>
{% endfor %}
</section>
<aside class="categories">
<h3>Categories</h3>
<ul>
{% for category in data.queries.categories %}
<li><a href="/category/{{ category.slug }}">{{ category.name }} ({{ category.post_count }})</a></li>
{% endfor %}
</ul>
</aside>
For JSON data queries, access the results similarly:
<section class="users">
<h2>Admin Users</h2>
{% for user in data.queries.admin_users %}
<div class="user-card">
<h3>{{ user.name }}</h3>
<p>Role: {{ user.role }}</p>
<p>Posts: {{ user.posts }}</p>
</div>
{% endfor %}
</section>
<div class="site-theme">
Current theme: {{ data.queries.theme_setting.value }}
</div>
You can also define queries in individual Markdown files:
---
title: "Author Profile"
queries:
author_posts:
source: "blog_db"
query: "SELECT title, slug, date FROM posts WHERE author_id = {{ author_id }} ORDER BY date DESC"
variables:
author_id: 123
---
# {{ author.name }}
## Recent Posts by This Author
{% for post in data.page_queries.author_posts %}
- [{{ post.title }}](/posts/{{ post.slug }}) - {{ post.date | date_format('%Y-%m-%d') }}
{% endfor %}
The above example shows how to define a query that fetches posts by a specific author using the author_id variable.
The most powerful feature of Presskit is generating multiple pages from database queries.
Mark a query as a generator to create multiple pages:
{
"queries": [
{
"name": "blog_posts",
"source": "blog_db",
"query": "SELECT title, slug, content, date, author FROM posts WHERE published = 1",
"generator": true,
"template": "post",
"output_path": "posts/#{slug}"
}
]
}
generator: true - Marks this as a page generatortemplate - Template to use for generated pagesoutput_path - Path pattern with placeholders like #{field_name}Create a template for your generated pages (templates/post.html):
<!DOCTYPE html>
<html>
<head>
<title>{{ title }} | {{ site.title }}</title>
</head>
<body>
<article>
<h1>{{ title }}</h1>
<time>{{ date | date_format('%B %d, %Y') }}</time>
<div class="content">
{{ content | safe }}
</div>
<p>By {{ author }}</p>
</article>
<nav>
<a href="/">← Back to Home</a>
</nav>
</body>
</html>
You can create parent-child query relationships:
{
"queries": [
{
"name": "authors",
"source": "blog_db",
"query": "SELECT id, name, bio, slug FROM authors"
},
{
"name": "authors.posts",
"source": "blog_db",
"query": "SELECT title, slug, date FROM posts WHERE author_id = {{ id }} ORDER BY date DESC"
}
]
}
The authors.posts query will automatically run for each row returned by the authors query. The query has access to the parent row's data (e.g. {{ id }} column), allowing you to create nested structures.
Access nested data in templates:
{% for author in data.queries.authors %}
<div class="author">
<h2>{{ author.name }}</h2>
<p>{{ author.bio }}</p>
<h3>Posts by {{ author.name }}</h3>
<!-- Nested data: Loop through posts for this author -->
{% for post in author.posts %}
<p><a href="/posts/{{ post.slug }}">{{ post.title }}</a> - {{ post.date }}</p>
{% endfor %}
</div>
{% endfor %}
In addition to configuring data sources in presskit.json, you can define data sources directly in the YAML frontmatter of individual files. This is particularly useful for standalone files or page-specific data.
---
title: My Page
description: A page with embedded data sources
sources:
users:
type: json
path: data/users.json
books:
type: json
path: books.json
---
# {{ title }}
## Users
{% for user in data.sources.users %}
- {{ user.name }} ({{ user.email }})
{% endfor %}
## Books
{% for book in data.sources.books %}
- **{{ book.title }}** by {{ book.author }}
{% endfor %}
Frontmatter source paths are resolved in the following order:
This means if you have a file at content/posts/article.md with a frontmatter source path data.json, it will look for:
content/posts/data.json first./data.json (current working directory) if the first doesn't existFrontmatter sources work alongside:
presskit.json (for full site builds)--source flag (for standalone compilation)data.sources.*Currently, frontmatter sources support:
type: json) - Load JSON data from files# Initialize a new Presskit project
presskit init
Creates the basic project structure with sample files including:
presskit.json configuration filecontent/ directory with sample index.mdtemplates/ directory with base.html and page.html# Execute queries and cache results
presskit data
# Build entire site
presskit build
# Build specific file
presskit build content/about.md
# Build with auto-reload (watches for file changes)
presskit build --reload
# Generate pages from generator queries
presskit generate
# Check query cache status
presskit status
Run data command before build or generate to ensure all queries are executed and data is cached.
# Start development server
presskit server
# Start development server with auto-reload
# (automatically builds if output directory is empty)
presskit server --reload
# Clean build artifacts and cache
presskit clean
# List available data sources
presskit sources
The compile command allows you to compile individual Markdown or HTML files without requiring a full Presskit project setup. This is perfect for creating standalone pages, documentation, or one-off content.
# Compile a single Markdown file
presskit compile page.md
# Compile HTML file with custom output path
presskit compile page.html --output result.html
# Compile with JSON data sources
presskit compile article.md --source users.json --source products.json
# Compile with custom template and config
presskit compile page.md --template custom.html --config site.json
# Compile HTML with frontmatter sources (sources defined in the file itself)
presskit compile standalone.html
--source - JSON data source files (can be used multiple times)--template - Template file to use (overrides frontmatter layout)--output - Custom output HTML file path--config - Path to presskit.json config file (optional)File Processing:
Data Sources:
--source file.json)data.sources.* in templatesTemplate Resolution:
layout from frontmatter or --template overridetemplates/ directory (if config exists) or same directory as input fileContext Available:
site.*, build.*, page.*, data.*)Simple Markdown with data:
# users.json contains: [{"name": "Alice", "email": "alice@example.com"}]
presskit compile article.md --source users.json
HTML with frontmatter sources:
---
title: Product Showcase
sources:
products:
type: json
path: products.json
---
<h1>{{ title }}</h1>
{% for product in data.sources.products %}
<div>{{ product.name }}: ${{ product.price }}</div>
{% endfor %}
Using custom templates:
presskit compile content.md --template newsletter.html --output newsletter.html
Presskit supports environment variables throughout your configuration using standard shell expansion syntax (${VAR} or $VAR). This is essential for keeping sensitive data like database passwords out of your configuration files.
Any string value in your presskit.json can reference an environment variable:
{
"title": "${SITE_TITLE}",
"url": "${SITE_URL}",
"sources": {
"database": {
"type": "postgresql",
"host": "${DB_HOST}",
"port": "${DB_PORT}",
"database": "${DB_NAME}",
"username": "${DB_USER}",
"password": "${DB_PASSWORD}"
}
},
"queries": [
{
"name": "posts",
"source": "database",
"query": "${POSTS_QUERY}"
}
]
}
Environment variables in all configuration values support both ${VAR} and $VAR syntax:
{
"sources": {
"data": {
"type": "sqlite",
"path": "${HOME}/data/blog.db"
}
}
}
# In your shell or .env file
export DB_PASSWORD="your-secure-password"
export SITE_URL="https://yoursite.com"
export DB_HOST="localhost"
# Run presskit
presskit build
{
"title": "My Blog",
"description": "A blog about web development",
"author": "Jane Developer",
"url": "${SITE_URL}",
"version": "2.1.0",
"language": "en-US",
"content_dir": "content",
"templates_dir": "templates",
"output_dir": "public",
"cache_dir": ".cache",
"default_template": "page",
"markdown_extension": "md",
"workers": "${BUILD_WORKERS}",
"server_host": "0.0.0.0",
"server_port": "${PORT}",
"sources": {
"blog_db": {
"type": "postgresql",
"host": "${DB_HOST}",
"port": 5432,
"database": "${DB_NAME}",
"username": "${DB_USER}",
"password": "${DB_PASSWORD}",
"options": {
"pool_min_size": 2,
"pool_max_size": 10
}
},
"analytics": {
"type": "duckdb",
"path": "data/analytics.duckdb"
},
"config": {
"type": "json",
"path": "${CONFIG_DIR}/site-config.json"
}
},
"default_source": "blog_db",
"variables": {
"environment": "${ENVIRONMENT}",
"analytics_id": "${ANALYTICS_ID}"
},
"queries": [
{
"name": "posts",
"source": "blog_db",
"query": "SELECT * FROM posts WHERE status = 'published' ORDER BY date DESC",
"generator": true,
"template": "post",
"output_path": "blog/#{slug}"
},
{
"name": "recent_posts",
"source": "blog_db",
"query": "SELECT title, slug, excerpt, date FROM posts WHERE status = 'published' ORDER BY date DESC LIMIT 5"
},
{
"name": "page_views",
"source": "analytics",
"query": "SELECT page, views FROM page_stats WHERE date >= current_date - interval '30 days'"
}
]
}
Presskit includes useful Jinja2 filters and functions:
date_format(format) - Format dates from YYYY-MM-DD to any format
{{ "2024-01-15" | date_format('%B %d, %Y') }}
<!-- Output: January 15, 2024 -->
flatten - Flatten a list of lists into a single list
{{ [[1, 2], [3, 4]] | flatten }}
<!-- Output: [1, 2, 3, 4] -->
stringify(sep=" ") - Convert a value or list of values into a string
{{ ["apple", "banana", "cherry"] | stringify(", ") }}
<!-- Output: apple, banana, cherry -->
is_truthy - Check if a value is truthy
{% if post.featured | is_truthy %}
<span class="featured">Featured</span>
{% endif %}
slugify(allow_unicode=False, sep="-") - Convert a string to a URL-friendly slug
{{ "Hello World!" | slugify }}
<!-- Output: hello-world -->
plainify - Remove all HTML tags from a string
{{ "<p>Hello <strong>world</strong></p>" | plainify }}
<!-- Output: Hello world -->
jsonify(**kwargs) - Convert an object to a JSON string
{{ {"name": "John", "age": 30} | jsonify }}
<!-- Output: {"name": "John", "age": 30} -->
humanize - Convert a number to a human-readable string
{{ 1234567 | humanize }}
<!-- Output: 1.23M -->
short_random_id(prefix="", k=8, seed=None) - Generate a random ID with optional prefix
<div id="{{ short_random_id() }}">Random ID</div>
<!-- Output: <div id="a7b2c4d8">Random ID</div> -->
<button id="{{ short_random_id('btn-') }}">Click me</button>
<!-- Output: <button id="btn-x9y4z2w1">Click me</button> -->
<input id="{{ short_random_id('input-', 12) }}">
<!-- Output: <input id="input-m5n8p3q7r2s6"> -->
template_debug() - Display all available template variables in a formatted, collapsible HTML structure
<!-- Add this anywhere in your template for debugging -->
{{ template_debug() }}
This function generates a nicely formatted HTML panel showing all template variables organized by category (site, build, page, data, other). Perfect for debugging template issues or exploring what data is available in your templates.
compile command for standalone file compilation, frontmatter support for HTML files, frontmatter data sources support, copy static assets with glob patterns, removed env: pattern for standard shell expansion with ${VAR} syntaxtemplate_debug() function for debugging templates--version flag for CLI--reload flag on build and server commands to watch for file changes and rebuild automaticallyFAQs
Static site generator
We found that presskit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports Scala and Kotlin, bringing AI-powered threat detection to JVM projects with easy manifest generation and fast, accurate scans.
Application Security
/Security News
Socket CEO Feross Aboukhadijeh and a16z partner Joel de la Garza discuss vibe coding, AI-driven software development, and how the rise of LLMs, despite their risks, still points toward a more secure and innovative future.
Research
/Security News
Threat actors hijacked Toptal’s GitHub org, publishing npm packages with malicious payloads that steal tokens and attempt to wipe victim systems.