Stasipy

A static site generator written in python.

This was mostly just done as a fun side project. I've always wanted to write a static site generator (text parsing is fun!), so here it is! It's not as full featured as I'd like it to be, and I suspect I'll hack on it for a long time as I need more and more features.

Probably not. There are many more complete options out there, but I'd be happy to continue maintaining the project if there is any interest.

To use from source:

1. Clone from github.
2. Create Virtual Environment.
3. Activate that Environment.
4. Install Requirements.

$ git clone https://github.com/blakfeld/stasipy
$ cd stasipy
$ virtualenv venv
$ . venv/bin/activate
$ pip install -r requirements.txt

To install via setup.py:

1. Clone from github
2. Run setup.py install

$ git clone https://github.com/blakfeld/stasipy
$ python setup.py install

To initialize a new site:

$ stasipy init ~/path/to/site --name "My Totes Rad Site"

To generate your new content:

$ stasipy generate ~/path/to/site

When you run the 'init' command, a new directory structure will be created for you. Inside that directory you'll find a src directory and a siteconfig.yml file. That src directory will contain several other directories that server various functions:

• meta: This is where you'll store partials for what I refer to as 'meta' pages. These are pages that require the entire state of the site to generate. In here you'll find things like index.html.j2, which requires the contents of all the posts before it can be rendered.
• page: This is where you'll store more static pages. The directory, as you'll note, is called 'page', as opposed to 'pages'. This is with a purpose. Each of these directories specifies a 'Document Type'. This 'Document Type' is what's used to select which template to use. The idea here is that down the line I can extend this to be whatever 'Document Type's I need. This actually came into play when I realized I needed 'meta' pages, and I was able to add those with minimal effort.
• post: This is where posts are stored.
• static: Files that should change infrequently, and that you would like served with no modification go here. Things like images, css, and javascript.
• templates: This is where Stasipy will look for your Jinja templates. By default, there is a layouts directory nested inside that will contain... well, your layouts.

Since I mentioned the config file above, now seems like a good time to talk about it. Stasipy reads the config file from the specified site directory. Anything in that config file will be available to your templates, so you can expose custom variables in there. There are some standard keys I use though:

• site_name: The name of your site.
• maintainer: The name of the person maintaining the site.
• maintainer_email: The maintainer's e-mail address.
• description: A description of your website.
• time_format: The datetime format to use.
• nav_items: Any custom nav items. This will be a YAML hash/dict that contains custom links you'd like on your nav bar. Note that anything that appears here will not be generated by Stasipy, so you can also use this to control ordering. The format looks like so:

      nav_items:
          - title: About Me
            href: /pages/about_me.html
  

Each document, regardless of contents, has some structure imposed on it. Mostly importantly metadata. Stasipy abuses the Markdown parser to allow you to put Markdown styled metadata in every document. This works since Jinja is valid inside HTML, and HTML is valid Markdown.

An example of this would be:

---
title: My Markdown Metadata Sample.
author: Corwin Brown
date: 06/09/2016
---

## What's the Deal with that?

Seriously? What's the deal with it?

The markdown metadata is the bits located between the two --- separators. It is just a set of new line separated key value pairs. While not mandatory, Stasipy anticipates that you've used all lowercase keys (There is a TODO to convert them). Also note that this metadata is made available to your document when being rendered. So you can do something like this:

---
title: My Markdown Metadata Sample.
author: Corwin Brown
date: 06/09/2016
---

## {{ title }}

Seriously? What's the deal with it?

Some fields are important and expected to be there. It won't crash if they're not, but things may not behave quite as you expect. For example, the date key. This is used to sort blog posts. If it is not present, Stasipy will attempt to figure out when the file was created using stat, but this is very likely not the sort order you want for your blog posts. Here's a listing of some of the more imporant keys:

• title: The title of the page/post. This is what appears in navigation menues.
• author: The author. If not supplied, Stasipy will use the 'maintainer' field in the siteconfig.yml file. If that is not configured, Stasipy will set it to None.
• date: The sort date for that documnet. This is mostly ignored on anything that isn't a post.
• navbar: Whether or not this page should display in the navbar. Defaults to True. Only affects pages.
• href: The link to the page. By default it will be /<document_type>/<document_title>.html
• template: The template to use to render the document. By default, it uses whatever is specified for that 'Document Type' in the src/templates directory.

• Pagination.
• Generate post summaries.
• In general the way post content is templated/rendered needs some tweaking.
• Add github styled code highlighting.
• Convert all metadata keys to lowercase.