Loïc Faugeron Technical Blog

Previously using Carew, the static website generator, this blog has now been migrated to Sculpin.

Both tools are really similar:

• they've been written in PHP
• they use both Symfony components and Twig
• they both generate HTML pages from markdown documents

However Sculpin has a better support and its author is a member PHP FIG. Let's see how it works

Github Pages

Github provides a service allowing people to host static webistes: Pages. The idea is simple:

1. create a reporitory with a name following this pattern: <username>.github.io
2. commit HTML files at its root and push
3. ???
4. profit

We can create a _sculpin directory at the root of the project, install inside it our Sculpin application with the page sources and finally generate the HTML files back in the root directory.

Installation

Installing Scuplin is very easy as a PHAR is provided:

curl -O https://download.sculpin.io/sculpin.phar
php sculpin.phar install
php sculpin.phar generate --watch --server

The generate command will convert all markdown files into HTML and the --server option will launch a local web server alowing us to preview the website in the browser.

Writing articles

Articles are written in the source/_posts directory and their name must be preffixed with their publication date (e.g. 2016-01-25-my-article.md).

Every page starts with a front matters:

---
layout: post
title: My Article
tags:
    - essay
---

The rest of the file is in standard markdown and will constitute the content of the page.

Publishing

Once happy with the changes, we can generate the final HTML:

php sculpin.phar generate --env=prod

The files will be located in output_prod. If we want to use Github Pages as described above, we simply need to move those files to the root directory:

cp -r output_prod/* ../

Then we simply need to commit all the changes and push.

Conclusion

Sculpin is quite simple to use: write some markdown files and let it generate HTML files out of it. It uses Symfony and Twig behind the scene making it really easy to extend.

Note: Migrating from carew has been a simple task. In my case it required:

• removing all link function usage and use instead markdown links
• configure permalink to :year/:month/:day/:filename.html in app/config/sculpin_kernel.yml to keep URL backward compatibility