Sculpin

I've started playing with Sculpin the static site generator written in PHP and Symfony. The idea is pretty cool - instead of having a CMS like Wordpress, needing a server running PHP, a database, needing to maintain plugins and security patches etc, Sculpin will convert markdown files to a static HTML website (old-school!). Then you just upload the generated HTML files to a webserver of your choice and serve these static pages. An advantage is this is far more efficient than running a full web application, and it requires a lot less of the maintenance and managements. You don't even need a webserver, you could just serve the static files from a web host like Amazon S3 or use GitHub pages for free!

It's not a new idea, there is a similar implementation in Ruby called Jekyll, but I decided to give Sculpin a go as its written in PHP.

It's ideal because I don't have very complex needs, I basically want to write text, with some code snippets and images here and there.

Installation

Installing Sculpin should have been quite simple, just download the phar and moving to my bin directory. Unfortunately there are some issues running Sculpin on PHP 7 with the latest downloadable phar so I cloned the latest source version from GitHub, and symlinked the binary executable from there to my bin dir instead. Sorted!

Using

I have found it quite easy to do most tasks following the documentation, but there a few things I didn't immediately understand from the docs that might be worth explaining.

sculpin.json and sculpin.lock are basically just composer.json and composer.lock but under a special Sculpin name. If you need to add a dependency, put it in the sculpin.json file and execute the sculpin update command.

The .sculpin directory is much like the vendor directory in a standard composer project, so you normally don't want to go touching files in there as it is managed by the Sculpin (composer) executables.

All of your content (posts and pages markdown files, images and other assets) go in the source/ directory. I find this a bit confusing because, as well as your content, it also mixes in your views, templates, and other files you may not expect to see in there. I would like to have these in separate locations.

The directories named starting output_* are generated by the sculpin application. This is the location where your final HTML, XML, CSS, JS, images etc. will be placed ready to be served. You will notice the directory suffixes map directly to the environments dev and prod. There are some differences here, for example posts tagged as draft only show in the dev environment. You probably don't want to manually edit any files in here, as any changes you make will likely be written over or lost when you next generate your site.

You can preview your site using the sculpin generate --watch --server command. The --watch option basically means generate will be called again every time a change is detected to your source files. The --server option is a shortcut to running the sculpin server command, it uses ReactPHP to create a local server, useful for testing, on http://localhost:8000 by default.

There is a handy bash file, publish.sh which contains a few sample steps you might use in order to deploy your site live, for example generating the production files, and rsyncing these to your web server. Simple, but effective! Because they are just static files you can probably get away with a relatively small, not-so-powerful webserver.

Issues

The only other problems I've run into is trying to pass variables into templates. There seems to be an index.html and blog.html template page in the source, which relate to the HTML files that are created, and I can edit the markdown at the top of the page to use variables in the scope. I just haven't figured out how to edit the template for a single post view.

And I'm not sure where I am supposed to put content that I don't want to be distributed into my web server, for example sass files, and raw markdown files. Maybe there is a way and I just can't find it in the documentation.

I wanted to update the theme slightly. I noticed it is using Bootstrap v2 so I decided to update that. I ended up creating a bundle to integrate Gulp, and using this to manage Bootstrap and my own custom SASS. Here's a post explaining that process