An Python-based static site generator using Jinja templates.
Project description
Jinjabread
A Python-based static site generator using Jinja templates.
Inspired by staticjinja, jekyll, and hugo.
Install
pip install jinjabread
Usage
Create new site project
python -m jinjabread new mysite
Build site
python -m jinjabread build mysite
Preview site locally
python -m jinjabread serve mysite
# Visit http://127.0.0.1:8000 in your browser.
Features
- Write pages in Markdown, HTML, or text.
- Use Jinja2 templating language in Markdown, HTML, or text.
- Supports YAML metadata in Markdown pages.
- Keep static media alongside static pages.
- Index pages (i.e.,
index.html) can list all other pages in the same directory. - Preview your static site locally with a built-in web server.
- Prettify all generated HTML (because why not?)
HTML pretty-printing
With prettify_html enabled (the default), jinjabread re-indents every generated page for readability. It is a rendering-preserving reformatter rather than a byte-preserving one, and it makes a specific contract:
- It preserves how the page renders. The output displays identically to the input: inline elements are never broken across lines, significant whitespace is kept, and
pre,textarea,script, andstylecontent is emitted verbatim. Only insignificant whitespace between block-level elements changes. - It is idempotent. Prettifying already-pretty output changes nothing.
- It adds no wrapper of its own. A body-level fragment, such as several top-level
<p>elements or plain text, is emitted as-is and is never wrapped in a<div>or<span>. - It parses and repairs markup. Every page round-trips through lxml's HTML parser, so unclosed tags are closed and misnested tags are corrected, matching how a browser reads the input. The output is always well-formed HTML; invalid or non-standard structure is not preserved verbatim.
- It distinguishes documents from fragments. A whole document, or a document-level element such as a lone
<script>or<head>, is emitted as a complete document with an HTML5 doctype; a body-level fragment is emitted without a doctype or wrapper.
File structure
Important files and directories
| Name | Description | Example path |
|---|---|---|
| Project directory | The project root | mysite |
| Content directory | Contains site content where each file becomes a site page | mysite/content |
| Layouts directory | Contains page layouts that gets used by the site content | mysite/layouts |
| Static directory | Contains static media that gets copied to the output directory | mysite/static |
| Output directory | The complete generated site, ready to be hosted | mysite/public |
| Config file | Custom site configurations in TOML format | mysite/jinjabread.toml |
Example: Site project structure
mysite/
├── content
│ ├── about.html
│ ├── index.html
│ └── posts
│ ├── index.html
│ ├── my-journey
│ │ ├── index.html
│ │ └── profile-photo.jpg
│ └── my-story.html
├── jinjabread.toml
├── layouts
│ └── markdown.html
├── public
│ ├── about.html
│ ├── index.html
│ ├── posts
│ │ ├── index.html
│ │ ├── my-journey
│ │ │ ├── index.html
│ │ │ └── profile-photo.jpg
│ │ └── my-story.html
│ └── static
│ └── style.css
└── static
└── style.css
Example: File to URL translation
| File path | URL path |
|---|---|
public/index.html |
/ |
public/about.html |
/about |
public/posts/index.html |
/posts/ |
public/posts/my-story.html |
/posts/my-story |
public/posts/my-journey/index.html |
/posts/my-journey/ |
public/posts/my-journey/profile-photo.jpg |
/posts/my-journey/profile-photo.jpg |
public/static/style.css |
/static/style.css |
Site config
Default config
content_dir = "content"
layouts_dir = "layouts"
static_dir = "static"
output_dir = "public"
prettify_html = true
[context]
[[pages]]
type = "jinjabread.MarkdownPage"
glob_pattern = "**/*.md"
layout_name = "markdown.html"
[[pages]]
type = "jinjabread.Page"
glob_pattern = "**/*"
Custom config
Change output directory
# jinjabread.toml
output_dir = "dist"
Add global Jinja context variables
# jinjabread.toml
[context]
site_name = "My site"
url_origin = "https://mysite.com"
Change Markdown layout file
# jinjabread.toml
[[pages]]
type = "jinjabread.MarkdownPage"
glob_pattern = "**/*.md"
layout_name = "post.html"
[[pages]]
type = "jinjabread.Page"
glob_pattern = "**/*"
Add page-specific Jinja context variables
# jinjabread.toml
[[pages]]
type = "jinjabread.MarkdownPage"
glob_pattern = "**/*.md"
layout_name = "markdown.html"
[[pages]]
type = "jinjabread.Page"
glob_pattern = "**/*.txt"
[pages.context]
foo = "bar"
[[pages]]
type = "jinjabread.Page"
glob_pattern = "**/*"
Pages types
| Page type | Keyword arguments |
|---|---|
jinjabread.Page |
- glob_pattern |
jinjabread.MarkdownPage |
- glob_pattern - layout_name |
Markdown pages
Markdown content supports full YAML metadata.
For example, given the following content and layout:
---
# content/my-blog-post.md
title: My blog post
author: John Smith
description: A very nice story.
keywords:
- thrilling
- must-read
---
It was a cold stormy night...
<!-- layouts/markdown.html -->
<h1>{{ title }}</h1>
<h2>{{ description }}</h2>
<h3>Written by {{ author }}</h3>
{{ content }}
Results in the following output:
<!-- public/my-blog-post.html -->
<h1>
My blog post
</h1>
<h2>
A very nice story.
</h2>
<h3>
Written by John Smith
</h3>
<p>
It was a cold stormy night...
</p>
Context variables
Default variables
All pages have these context variables:
| Name | Description | Example value |
|---|---|---|
url_path |
The URL path of the current page | / |
file_path |
The file path of the current page, relative to the output directory | index.html |
Variable precedence
Page-specific context variables override global site context variables.
For example:
# jinjabread.toml
[context]
fee = "fie"
foe = "fum"
[[pages]]
type = "jinjabread.Page"
glob_pattern = "**/*.txt"
[pages.context]
foe = "foo"
[[pages]]
type = "jinjabread.Page"
glob_pattern = "**/*.html"
[pages.context]
foe = "bar"
.txtpages will have the following extra context variables:fee = "fie" foe = "foo"
.htmlpages have the following extra context variables:fee = "fie" foe = "bar"
Index pages
All index pages (i.e., index.*) has an extra context variable named pages which is list of dictionaries of context variables from its sibling files.
For example, given the following file structure:
mysite/content/posts/
├── index.html
├── post1.md
└── post2.md
You can list all the pages in the posts directory using:
<!-- mysite/content/posts/index.html -->
{% for page in pages %}
<a href="{{ page.url_path }}">
{{ page.url_path.split('/') | last | title }}
</a>
{% endfor %}
Resulting in:
<!-- mysite/public/posts/index.html -->
<a href="/posts/post1">Post1</a> <a href="/posts/post2">Post2</a>
Contributing
Setup
Install uv (https://docs.astral.sh/uv/getting-started/installation/), then:
uv sync
Test
uv run python -m unittest
Build
uv build
Release
export TWINE_USERNAME='__token__'
export TWINE_PASSWORD='secret-token'
uv run twine upload dist/*
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
jinjabread-0.7.0a1.tar.gz
(82.7 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file jinjabread-0.7.0a1.tar.gz.
File metadata
- Download URL: jinjabread-0.7.0a1.tar.gz
- Upload date:
- Size: 82.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
524bb42ea0673911b052678173d259b90c898df92b4428371483e45cc8177ddd
|
|
| MD5 |
424721f1647117da50adfae7282d5ddf
|
|
| BLAKE2b-256 |
f1e36658ba00e2c80e83bfd8514fb605a83091068adc45a5854713cc0bd835c8
|
File details
Details for the file jinjabread-0.7.0a1-py3-none-any.whl.
File metadata
- Download URL: jinjabread-0.7.0a1-py3-none-any.whl
- Upload date:
- Size: 15.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bddc526514f54feeadbec7e819a670a2ff4eb0ad67b1caf714877b768f5836e2
|
|
| MD5 |
11f526d36906ef961a33d75d70870682
|
|
| BLAKE2b-256 |
234280112486466656ea6dd151d8912564745ebdb675354d00ca09f65d73ba7a
|
