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?)

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>
<p>{{ content }}</p>

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>
  <p>
    It was a cold stormy night...
  </p>
</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

python -m venv venv && \
  . venv/bin/activate && \
  pip install pip pip-tools --upgrade && \
  pip-sync requirements.txt

Test

python -m unittest discover .

Build

python -m build

Release

export TWINE_USERNAME='__token__'
export TWINE_PASSWORD='secret-token'
python -m twine upload dist/*