casaubon/README.md~

# Casaubon

Casaubon is a static site generator written in Rust. I had very specific goals
in mind when writing Casaubon and it is not meant to be all things for all
people. Casaubon does what it is intended to do and no more.

### Goals

- Convention over configuration
- Learn Rust
- Fast compile times

### Non-goals

- Extensibility
- Flexibility

## Installation

(requires [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html))

```
$ cargo install casaubon
```

## Run tests

```
$ cargo test
```

## Usage

Create a new project

```
$ casaubon new
```

Generate HTML files

```
$ casaubon build
```

Watch files for changes and rebuild. Note that there is no dev server built in.

```
$ casaubon watch
```

`build` and `watch` both accept a `--drafts` flag if you wish to include drafts
in the generated HTML files.

## Configuration

Casuabon is not intended to be as flexible as most static site generators.
Currently, the only configuration option is the name of the site, which can be
set in `casaubon.toml`.

## Writing

Casuabon expects the first line of post files to consist of a `#` followed by a
space and the name of the post, followed by two newlines. For example:

_posts/first-post.md_

```
# First Post

Lorem ipsum dolor sit amet....
```

In this example, the post's title would get parsed as "First Post", and the
post's body would get parsed as "Lorem ipsum dolor sit amet...". The slug gets
parsed from the filename, and in this case would be 'first-post'.

## Templates

Casaubon creates a number of templates for you in the `templates` directory.
These include:

|Title                   |Description|
|------------------------|-----------|
|`layout.html`           |The main layout. All page content gets injected into the `{{ contents }}` variable. The title of the page is available in the `{{ page_title }}` variable.|
|`post.html`             |The template for rendering a single post. Variables available include `{{ title }}` and `{{ body }}`.|
|`page.html`             |The template for rendering a single page. Variables available include `{{ title }}` and `{{ body }}`.|
|`post_listing.html`     |This template is for the list of posts on the index page. The `{{ post_listing }}` variable contains the result of compiling the `post_listing_item.html` template against each post.|
|`post_listing_item.html`|This template determines how each post will appear in the main listing. Variables available include `{{ title }}` and `{{ slug }}`.|