Walkthrough

Before starting your first Statik project, you've got to understand that it isn't geared to only produce blogs, where the majority of other static site generators seem to be dedicated to blogs and the like.

Step 1: Create project skeleton

After installing Statik, create yourself a directory somewhere for your project with the following sub-directory structure:

models/    - This is where your data models will go.
data/      - This is where your data will go.
templates/ - Your site templates will go here.
views/     - Configuration setting up your views (i.e. how your URLs/data/templates are processed) will go here.
assets/    - All of the static files (JavaScript/CSS/images/etc.) for your project will go here.

Step 2: Set up your project configuration

Create a config.yml file in the root of your project, with the following (YAML) format:

project-name: My Project's Name
base-path: /

project-name

This is purely for informational purposes.

base-path

Sometimes you'll want to serve your generated static site from a non-root location on your web server (e.g. http://somewhere.com/mysite/ instead of from http://somewhere.com). Statik generates URLs in a relative manner, so this base-path value is prepended to all generated URLs in your templates.

Step 3: Define your data models

Statik uses SQLAlchemy under the hood to build up an in-memory SQLite database from which your views and templates can execute queries. You define your models in YAML format.

Sample model: models/Post.yml

title: String
slug: String
author: Author       # This will be auto-detected as a foreign key reference
summary: String
published: DateTime
content: Content

Sample model: models/Author.yml

first-name: String
last-name: String
email: String

These will be converted into SQL database tables in your in-memory SQLite database while building your project.

Step 4: Define your data

So now that you've defined what your database "tables" will be, you need some data in those tables to make your site useful. Data can either be defined in YAML format, or in Markdown format.

For each of your models, create a subfolder in your project's data/ folder as such:

data/Author/ - Where your site's "Author" model instances will be stored.
data/Post/   - Where your site's "Post" model instances will be stored.

Each .yml or .md file in each of those folders will represent an instance of the relevant model, with the file name of the file itself becoming the primary key of that particular instance. So, a file called michael.yml in the data/Author folder will be inserted as an entry whose primary key is michael into the Author in-memory database table.