pyblog

PyBlog

A lightweight python static blog generator - 0.6.3

Installation

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

.. code:: bash

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

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

.. code:: 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 new:

.. code:: 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:

.. code:: 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:

.. code:: 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:

.. code:: 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:

.. code:: 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 | +---------------+--------------------------------------------------------+