Loïc Faugeron Technical Blog

Carew, the static site generator 01/01/2014

Deprecated: This article has been re-written - see Scuplin

Frameworks are a real help when building web applications which serve business logic. But what about static websites?

Those only contain pages which could be directly written in HTML. The only problem with this approach is that HTML isn't writter friendly compared to Markdown.

Also, we could say that static websites like blogs do have some logic behind the scenes:

But still, a framework might be too much for this task.

Static site generators are a way to solve this problem:

  1. simply write your pages in markdown
  2. launch a command to generate HTML from it

Carew is one of them (among Jekyll, Hyde, Poole and Lanyon): it is written in PHP, allows you to use the template engine Twig in your markdown and it provides a theme using Bootstrap.

This blog post will focus on Carew, as this very blog is written with it.

Carew and Github

A common way to quickly publish static sites is to use Github Pages which works as follow:

  1. create a repository, the name should follow this format: <username>.github.io
  2. add, commit and push the content of the web directory directly at the root of your repo
  3. the site is now available at this address: http://<username>.github.io

Learn more about hosting a website built with Carew on the official website.

Creation

Creating your site using Carew is very simple, just follow these steps:

$ php composer.phar create-project carew/boilerplate <project> -s dev
$ cd <project>
$ bin/carew build

Examples pages (which sources are located in pages and posts) are converted from markdown to HTML in the web directory.

Customization

Before writing any page or post, edit the configuration wich is located inside the config.yml file.

Then edit the pages/index.md and pages/about.md pages with your own content.

Finally, remove the content of the posts folder and create your first blog post using this command:

$ bin/carew generate:post [--date='YYYY-MM-DD'] title

See the configuration documentation on the official website.

Front matters

Each markdown file starts with a header:

---
layout: post # no need for this line when writing a regular page
title: Will be used by `<title></title>` and `<h1></h1>`
tags:
    - first tag
    - carew
---

Carew generates a page listing all existing tags. You can create a link to this page with the following snippet:

{{ link('tags', 'The page with all the tags') }}.

Learn more about Front matters on the official website.

Conclusion

Carew is really simple to use, in this article we've covered the minimum you should know to create pages, blog posts and tags.

I hope you enjoyed this article and that it helped you a little.

If you want to learn more, for example to customize its behaviour or its theme, please refer to the official documentation.