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``:

.. 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-init``:

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