Obraz - static site generator in a single Python file similar to Jekyll

Why?

There are many static site generators. Why choose Obraz?

Python: Written in the Python language
< 500: Single source file less than 500 lines of code
Jekyll: Mostly compatible with the popular Jekyll

News

2012-12-19

Obraz 0.3 Released

In this release the command line arguments have been changed to be more informative for new users. The help message is shown by default.

Also the plugin interface has been extended in order to provide an extension point for adding custom Jinja2 filters. The plugin system added in Obraz 0.2 is still considered experimental.

What's new:

Site path as a required command line argument
obraz.template_filters extension point for adding custom Jinja2 templates
markdownify template filter as in Jekyll
obraz.filters extension point renamed to obraz.file_filters

2012-11-15

Obraz sites

2012-06-08

Obraz 0.2.1 Released

2012-06-02

Obraz 0.2 Released

2012-05-27

Obraz 0.1.2 Released

Archive...

Users

This is the list of several sites that are generated using Obraz:

Development

The source code is available on the Bitbucket:

$ hg clone https://bitbucket.org/vlasovskikh/obraz

Bug reports, feature requests, and contributions are welcome!

Quickstart

Let's create a statically generated blog!

Install Obraz from the Python package index:
```
$ pip install obraz
```

Create your own blog in the /path/to/blog directory:

.
|-- _layouts
|   |-- default.html
|   `-- post.html
|-- _posts
|   |-- 2012-05-24-hello-world.md
|   `-- 2012-05-25-second-blog-post.md
`-- index.html

The _layouts directory contains layout templates. default.html contains the default layout for all the site pages:

---
---

<!DOCTYPE html>
<html>
  <head>
    <title>My Blog - {{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

post.html contains the layout for blog posts. It uses the default layout in its YAML front matter:

---
layout: default
---

<div class="entry">
  <h1>{{ page.title }}</h1>
  <p>Created at {{ page.date }}.</p>
  {{ content }}
</div>

2012-05-24-hello-world.md is the first blog post in Markdown. The publication date is specified in the filename using Jekyll conventions. It is based on the post layout:

---
layout: post
title: Hello, World!
---

This is my _first_ blog post!

It uses:

* YAML for metadata
* Markdown for formatting
* Obraz for static generation

2012-05-25-second-blog-post.md is just another blog post:

---
layout: post
title: Second Blog Post
---

Just another blog post.

index.html is the start page of the blog. It contains the list of recent posts:

---
layout: default
---

<div>
  <h1>My Blog</h1>
  <p>Welcome to my blog!</p>
  <ul>
  {% for post in site.posts %}
    <li class="entry">
      <span class="date">{{ post.date }}</span>
      <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
  </ul>
</div>

Generate your site using Obraz:
```
$ obraz /path/to/blog
```
The generated files will appear in the /path/to/blog/_site directory.
Run the web server:
```
$ cd /path/to/blog/_site
$ python -m SimpleHTTPServer 8000
```
and check the results in the browser by visiting http://localhost:8000/. You got your first Obraz blog up and running! Now it's time to play with the design and customize things.

For more details refer to the Jekyll documentation and the list of differences from Jekyll.

See also the source code of various sites using Obraz for examples of using RSS feeds, Markdown pages, tags, custom URLs, etc.