========
Tutorial
========
Part 0: Overview
----------------
Complexity is a refreshingly simple static site generator, for those who like to
work in HTML. It allows you to quickly see how your changes affect your site.
This quick tutorial will show you how to run this generator on your own using the
most basic structure possible. Just type the given instructions into your terminal.
If you have any specific questions you may find help in the documentation:
http://complexity.readthedocs.org/en/latest/
Or on the Github page: https://github.com/audreyr/complexity
This is the directory structure for a minimal Complexity site::
my_repo/
├── project/ <--------- input
│ ├── assets/
│ │ ├── css/
│ │ ├── js/
│ │ └── img/
│ │
│ └── templates/
│ ├── base.html
│ ├── index.html
│ └── about.html
│
└── www/ <---------- output
├── index.html
├── about/
│ └── index.html
├── css/
├── js/
└── img/
Part 1: Setup
-------------
First, grab a copy of the example Complexity site::
git clone https://github.com/audreyr/complexity-example.git
Open everything in a text editor. You should see a main `project/` directory
with subfolders for your work:
* Study the template files in `templates/`. We'll go over them shortly.
* Notice the `assets/` directory. That is where you put your static files.
* Creating additional directories in `assets/` (e.g. `ico/`) is fine; they'll get
copied over to `www/` without modification.
At the same level as `project/`, a `www/` directory will be auto-generated.
It will contain your final rendered templates and optimized static assets.
When you're done, you should have a project structure like that in
https://github.com/audreyr/complexity-example.
Part 2: What's in a Complexity Site?
------------------------------------
Here's what a very simple Complexity site looks like:
`project/templates/base.html`:
.. code-block:: html+jinja
{% block title %}{% endblock %} - Built with Complexity
{% endblock %}
Notice how `index.html` and `about.html` both share a common parent template,
`base.html`.
Part 3: Generate the Site and Serve It Locally
----------------------------------------------
Run the `complexity` command, passing it input and output directories::
$ complexity project/
This results in the following:
* A `www/` directory gets created, containing your generated static HTML site.
* Templates are rendered and output to files smartly:
* Any templates starting with "base" are assumed to be parent templates
and not rendered on their own (e.g. `base.html`, `base_section.html`)
* Templates named `index.html` are output to the same corresponding
locations in `www/`.
* Other templates are expanded in order to hide the ".html" extension.
For example, `about.html` is expanded to `about/index.html`.
* A lightweight server starts up locally, serving your site so that you can see
how it looks and check that everything works.
Open a web browser to http://127.0.0.1:9090. You should see your newly generated site!
In an upcoming release, the following will also occur during Complexity's
generation process:
* CSS will be minified and concatenated.
* SCSS and/or LESS will compiled to CSS, then minified and concatenated.
* JS will be minified, concatenated, and obfuscated.
Development is happening at a rapid pace, so stay tuned. To keep updated, watch
and star https://github.com/audreyr/complexity on GitHub.
Part 4: Upload the Site to Amazon S3
-------------------------------------
For site deployment we'll use the "alotofeffort" tool. It is designed for
use with Complexity, but it works with non-Complexity sites just as well.
Install it::
$ pip install alotofeffort
Save the following in `~/.boto`::
[Credentials]
aws_access_key_id = ...
aws_secret_access_key = ...
Replace `...` with your AWS access credentials, of course.
Then deploy the `www/` directory to any S3 bucket that you own::
$ alotofeffort www/ your-s3-bucketname
Your site is now live! Go to the URL that `alotofeffort` prints out after
it finishes uploading.
Point your domain name at that URL, and you'll be done!