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:
- posts can have a state (is it published yet?)
- posts can be tagged, in order to make them easier to find
But still, a framework might be too much for this task.
Static site generators are a way to solve this problem:
- simply write your pages in markdown
- 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:
- create a repository, the name should follow this format:
<username>.github.io
- add, commit and push the content of the
web
directory directly at the root of your repo - 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.