stanley 1.4.2

Flat file blog tool bult on Jinja2 templates

version: 1.4.1

Installation
============

You can install Stanley using `pip` (http://pypi.python.org/pypi/stanley)

sudo pip install stanley

or clone this repo and run setup.py

git clone git://github.com/glenswinfield/stanley.git
cd stanley
sudo python setup.py install

Usage
-----

> The functionality of this code is very basic at the moment - just enough to run my own blog (http://blog.glenswinfield.co.uk) which doesn't have a lot of requirements. I'll be adding/adapting features as I need them.
To see the project setup that powers my blog see: https://github.com/glenswinfield/blog

You can structure this file however you like, it is just parsed as YAML and passed to the templates, I use the `global` keword, but it's arbitrary.


Create a Project
----------------

To initialize an skeleton file structure use `python /my/site-packages/stanley/bin/project "project_dir"` this will create a directory structure inside the directory specified contains config.yml and a satanly utils file - like this:
/content
/site
/static
/templates
config.yml
config.dev.yml
stanley

This will NOT overwrite existing files, just create those that are missing.

Config
------

This file exists in the root of the application and defines variables that will be globally available in all templates. A good place to start would be:

global:
site_url: "http://dogsvscatsvshumans.net"
site_title: "My Site"
static: '/static' # convinience to reference the directory holding static files (css/js/img etc)


Build .html Site
----------------

To build .html files from your content use `python stanley build --config=config.yml`. This will take all of the files in `content`, parse them as markdown, convert the YAML front matter and render it into its specified template and save it in the `site` directory. The static folder is then copied across as-is.

Templates
---------

Templates are Jinja2 http://jinja.pocoo.org/ there is no functionality added or removed.

Looping over content/posts/entries
----------------------------------

Looping over entries uses existing Jinja2 functionality with the stanley.Posts object, you use it like this:

{% for post in posts.category('/blog').limit(5).result %}
// do whatever
{% endfor %}

For all of the posts just use:

{% for post in posts.result %}
// do whatever
{% endfor %}


Each of the available filter methods in `posts` return a new `posts` object with a `result` attribute that is the filtered set of posts. Filters are:

* category
* orderby('field', descending[true/false])
* limit()

The default set is all results.

Front Matter
------------

The YAML front matter - as used by Jekyll - is a block at the head of content files that contains data that you want passed to it's template when it is rendered.

A `template` parameter is required or an exception will be thrown when you run the build script. Typically a content file might look like this:

---
template: blog.html
title: This is the title of my page
some_other_thing: Red
daft: true # this prevents the post from being published if the notdraft() filter is used
---

This is the body content

Additionally some global variables are available in all templates. You define these in your config.yml.

Server
------

During development you might want to see your site rendered, you can use Flask to kick off a server on 0.0.0.0:5000 - each page refresh will trigger a `--build` and return the content you specify. *This is a very rough implementation and is something that I will be working on*.

Start the server with `python stanley server --config=config.yml` then visit `http://0.0.0.0:5000` to see the generated site.