Getting started: quick start

Requirements

Installation

Use your preferred Python package manager to install blurry-cli:

# Poetry
poetry add blurry-cli

# uv
uv add blurry-cli

# Pipenv
pipenv install blurry-cli

# pip
pip install blurry-cli

Directory structure

A Blurry project uses a simple directory structure consisting of a content directory for Markdown site content and a templates directory for Jinja templates used to generate HTML pages from that Markdown content. Blurry outputs a built site into dist/ by default, and this is configurable in Blurry's settings.

Blurry's directory structure is used as the website's navigation structure, with just a little magic:

index.md files generate index.html files
other Markdown files, like about.md, generate a file like about/index.html, which makes for clean, SEO-friendly URLs
files that end with .jinja are processed with Jinja and generate a file with the .jinja extension removed, like feed.xml.jinja -> feed.xml
images are copied and generated at multiple sizes. See Content: Images for more information
other files are copied as-is

For example, this Blurry project:

.
├──🗀 content
│  ├──🗎 index.md
│  ├──🗎 about.md
│  └──🗀 posts
│     ├──🗎 index.md
│     ├──🗎 feed.xml.jinja
│     └──🗎 welcome.md
├──🗎 robots.txt
└──🗀 templates
   ├──🗎 base.html
   ├──🗎 AboutPage.html
   ├──🗎 Blog.html
   ├──🗎 BlogPosting.html
   └──🗎 HomePage.html

Will result in the following URLs:

/
/robots.txt
/about/
/posts/
/posts/feed.xml
/posts/welcome/

Content

Blurry content files are Markdown files with front matter, which is a common pattern in other static site generators like Hugo and Jekyll. Blurry's front matter is written in TOML. The front matter should conform to a Schema.org Type, and the front matter is passed into the template as template context for the Jinja template named after the schema type. The Markdown content is converted to HTML and is added to the Jinja template context as body.

Let's look at the homepage for Table to Markdown, a site built with Blurry:

+++
"@type" = "WebApplication"
name = "Home"
abstract = "Table to Markdown is a simple Markdown table generator that converts tables from spreadsheet applications and websites into well-formatted Markdown tables."
+++

# Easy Markdown Tables with Table to Markdown

<div class="custom-element-container">
  <table-converter></table-converter>
</div>

## A beginner's guide to Markdown

In the [original Markdown spec](https://daringfireball.net/projects/markdown/), John Gruber describes Markdown as "a text-to-HTML conversion tool for web writers."

[...]

Templates

The corresponding WebApplication.html template file might look like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="description" content="{{ abstract }}">
    <title>{{ name }}</title>
    {{ schema_type_tag|safe }}
    {{ open_graph_tags|safe }}
</head>

<body>
  {{ body|safe }}

  <p>Published by: {{ author.givenName }} {{ author.familyName }}</p>
</body>
</html>

See the Templates: syntax and Templates: context docs for more information, and Templates: examples for simple and more advanced templates.

Commands

Blurry can build a static site to prepare for deployment, or it can be run as a server with live reload.

To build for production (docs), run:

blurry build

To start the development server (docs), run:

blurry runserver

Then visit http://127.0.0.1:8000 in your browser to see your site. The site is rebuilt when files in the templates and content directories are modified.