Skip to content

README.md

Latest commit

 

History

History
353 lines (270 loc) · 9.15 KB

README.md

File metadata and controls

353 lines (270 loc) · 9.15 KB
Raw

Jinjabread

CircleCI GitHub release PyPI downloads License

A Python-based static site generator using Jinja templates.

Inspired by staticjinja, jekyll, and hugo.

Install

Requires Python 3.11 or newer.

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, and style content is emitted verbatim. Only insignificant whitespace between block-level elements changes.
  • It is idempotent. Prettifying already-pretty output changes nothing.
  • It ends every file with a single newline. Non-empty output is terminated with exactly one \n, following the POSIX convention that a text file's last line ends in a newline. Empty input stays empty.
  • 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"
  • .txt pages will have the following extra context variables: 
    fee = "fie"
foe = "foo"
  • .html pages 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/*