# blatter

Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

-- restructuredtext --

## blatter

Blatter is a tiny tool for creating and publishing static web sites built from dynamic templates.

When developing your site, you can work locally on your own computer and view your work through a local web server Blatter provides. All of your URLs will work, relative and absolute. And if you choose to use dynamic templates for including common elements like headers and footers, (or for more advanced templating features), those templates will be rendered on the fly as you make changes and refine your work.

When you're satisfied with your changes, you can 'blat' the project out into a folder containing a purely static version of the site.

Static files like images and css are copied over, and all of the dynamic templates are rendered into a final static form. The finished product can then be uploaded to the live web site and published immediately.

### Tutorial

Get started with blatter init:

$blatter init --hello-world Blatting... Created directories static, templates, site, out Created blatter.ini Created hello world content. Try it out with 'blatter serve' and 'blatter blat'. Done.  The --hello-world creates a sample project for you. There's some static content (an image) and some templates: $ ls *
blatter.ini

out:

site:
index.html

static:
images/

templates:
base.html


Anything in 'site' will be rendered as a template and is available as a URL. Anything in 'static' is available as a URL too: the two directories are combined together.

The 'templates' directory will also be searched for templates but is not included in URLs. It's a handy place to keep template fragments and utilities that you want to use in published pages.

You can start a local web server:

$blatter serve Blatter server starting for: http://localhost:8008/ * Running on http://localhost:8008/ * Restarting with reloader... ^Z  And if you fetch the / URL, blatter renders the template site/index.html and serves up the static/images/dot.png. You'd do it in a web browser, but here we'll show it in text: $ curl http://localhost:8008/

<html>
<title>hello world!</title>
<body>

<p>
<img src="images/dot.png">
blatter success!
</p>

</body>
</html>


Satisfied with that, blatter will publish the entire site, combining everything in static with a rendered version of everything in site:

$blatter blat Merged static into out Generated 1 files in out$ ls out
images/   index.html
$cat out/index.html <html> <head> <title>hello world!</title> </head> <body> <p> <img src="images/dot.png"> blatter success! </p> </body> </html>  You can even send that directly to a remote server if you like:$ blatter publish --destination=www.my.host:/var/www/mysite/htdocs/

### Configuration

blatter init will create a basic configuration for you in blatter.ini. Any of the directories can be changed to suit your tastes.

Custom Jinja filters can be also be imported. Say you have a filter called uppercase in a filters.py file that you'd like to use. To import the filter you would add the following to your blatter.ini file:

[filter.uppercase]
name=uppercase
function=filters.uppercase


The name option is the name that Jinja will use to refer to the filter in your templates. The function option is the full module path to the function you want to import as a filter.

### Nested Sites and Chaining Blatters

If your site will reside somewhere other than / on the remote server, you can set the url_prefix configuration option to match the prefix on the remote server, for example '~jek/'.

Blatter can also manage multiple sites within a single virtual server. Say you have the following structure:

/*
/products/blatter/*
/products/squiznart/*


Each of these can be its own blatter project. Each of the products/... projects would set their url_prefix to match the desired final URL.

If a /products/... project needs to use resources from the root (/), such as /images/logo.png, the two projects can be linked together during development so that URLs will resolve in the built-in web server and you'll see all those shared images.

The only prerequisite for linking is that both blatter projects be available on the filesystem. To enable linking, configure the fallbacks for the project. If a URL can't be found in the project by normal means, each of the fallbacks will be tried in turn. If the fallbacks themselves have fallbacks, they're tried as well.

In the blatter.ini:

url_prefix=/products/blatter

fallbacks=root_website
[fallback.root_website]
location=../root_website


### Ignoring Files

Files can be ignored by creating a file named ignore in the same location as blatter.ini. The file should consist of one file/directory name per line. No wildcards are supported. The ignore applies recursively. For example, if you have an ignore file like:

index.html


then ALL of the following would be ignored:

/static/index.html
/static/dir/index.html
/site/index.html
/site/dir/sub/dir/index.html


This feature should be considered extremely experimental. It works well for excluding a .hg or CVS directory if you keep your content under version control but probably isn't good for much else yet.

### Author

Jason Kirtland <jek@discorporate.us>

# Recent activity

Commits by Steve Losh were pushed to durin42/blatter

a4d2f0c - Add any directories that a blatter config file is in to the Python path. This makes sense because configs should be able to specify filter ...
f3cd950 - Fix the filter importing problem.
63bdb86 - Fix up the README because I clearly do not know restructuredtext very well.
3c1a084 - Convert the spaces to tabs in the README to work as ReST.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.