pyblog 0.5.2

Dirt-simple static blog general

PyBlog
======

A jinja-based, extremely basic python static blog generator

Installation
------------

The simplest way to install PyBlog is through one of the Python package
managers, `pip` and `easy_install`:

````bash
$ [sudo] pip install pyblog
$ [sudo] easy_install pyblog
````

Alternatively, you can download or clone this repository, and install the tool
manually:

````bash
$ git clone https://github.com/cesarparent/pyblog.git
$ python setup.py install
````

Creating a Blog
---------------

The first step in setting up a PyBlog blog is to create the directory structure.
You can do this by calling `pyblog-init`:

````bash
$ mkdir new-blog && cd new-blog
$ pyblog new .

# or...

$ pyblog new new-blog && cd new-blog
````

The tool will create the following directory structure, along with the PyBlog
configuration file:

````text
|_ _pages/
|_ _posts/
|_ _static/
|_ _templates/
|_ config.txt
````

* `_pages` contains any file that you'd like PyBlog to process and potentially
run through templates. It will keep the same filename and be placed at the
root of the generated blog (for example, the index & about pages, or an RSS
feed).

* `_posts` contains your posts. They should be `.txt` files, and can contain
any kind of content (at the moment, the only content filter available to
templates is `markdown`).

* `_static` contains any file you want to be copied without any tampering to
the output directory (images, CSS and the likes)

* `_templates` contains your Jinja2 template files. Any file present in the
directory is available for posts and pages to use.

Once the blog is set up and you've written some post, the blog is generated by
calling:

````bash
$ pyblog build [-s /source] [-d /destination] ...
````

If you want PyBlog to re-generate your blog every time a file changes in the
source directory, you can add the `--watch` flag. You can also spawn a local
development server with:

````bash
$ pyblog serve [-s /source] [-d /destination] [-H host] [-P port]
````

By default, your blog is available at `http://localhost:4000`. When running the
development server, `--watch` is enabled.

Writing Posts
-------------

Posts are simple, static plain-text files with a HTTP headers-based metadata
section:

````text
title: Some great post
date: 2016-09-07 14:00:00
template: post.html

Hey! This is a post written for the PyBlog demo.
````

`title` and `template` are required. Title is used to generate the post's final
URL/filename, and template indicates which template file should be used for
rendering. If `date` is not specified, the file's last-modified date is used.

Writing Pages
-------------

Pages follow exactly the same model. If the `template` field is omitted, the
contents of the file will just be output "as is". If a page has no metadata
section, it will be rendered without a template. Pages can contain any Jinja2
template code.

Template Objects
----------------

Every template gets passed a `blog` object on rendering, which contains the
following fields:

| field | description |
|:---------------|:---------------------------------------------------------|
| `name` | The blog's name, as specified in `config.txt` |
| `tagline` | The blog's tagline, as specified in `config.txt` |
| `root_url` | The blog's root url, as specified in `config.txt` |
| `get_posts()` | The blog's posts, in reverse-chronological order |
| `get_pages()` | The blog's pages, in reverse-chronological order |

When rendering a post or a page, a `post` object is also available:

| field | description |
|:---------------|:---------------------------------------------------------|
| `title` | The post's title |
| `slug` | For post's, a url-safe title, for pages the filename |
| `url` | The post's url relative to the blog's root |
| `date` | The post's publication date |
| `content` | The post's content |