How To Install And Start Using Sculpin

Sculpin is a PHP based static site generator. It converts Twig or HTML templates together with content written in markdown into an easily deployable static site.

In this tutorial, we will install Sculpin on our VPS running Ubuntu 12.04 and get started using it. We will see how to start a project from scratch, how to generate the static files, and how to use its internal web server to deliver the files to the browser. Additionally, I’ll show you how you can get started with a pre-made blogging site built in Sculpin and add new blog posts to it.

The first thing we need to do is take care of some of the requirements we will need later. So run the following commands to install them. If you already have any of them, you can just remove them from the command.

apt-get update
apt-get install php5-common php5-cli git-core php5-curl

Then we download the Sculpin PHP executable (the .phar file):

curl -O https://download.sculpin.io/sculpin.phar

Next, we need to make it executable:

chmod +x sculpin.phar

Now in order to run Sculpin from any folder on our virtual server, let’s move it into the /bin folder:

mv sculpin.phar ~/bin/sculpin

If you don’t yet have the /bin folder in your user’s root folder, go ahead and create it before. And finally, let’s add it to the bash. Open the .bashrc file:

nano ~/.bashrc

And paste in the following line:

PATH=$PATH:$HOME/bin

Then run the following command to source the .bashrc file and make sure your changes stick:

source ~/.bashrc

And that should do it. To test if the command works, run just the sculpin command from any folder (sculpin) and you should get the Sculpin help in the command terminal.

One thing about Sculpin is that it comes with a built-in webserver capable of serving its pages to the web. To see this in action, let’s create our simple site in our user’s root folder and not the Apache root directory. Let’s start with our first project folder:

mkdir mysite
cd mysite
mkdir source
cd source

Now we have the project folder (mysite/) and another folder inside (source/). The latter is where you will put your site’s content. So let’s create a simple Hello World thing in there. Create an index.md file in the /source folder and paste the following:

---
---

# Hello World

The format with which we are writing the Hello World is called markdown and the lines above are for YAML formatting. For more about markdown syntax, check this page. Save the file, exit, go back to the mysite/ folder and run the following command:

sculpin generate --watch --server

This will generate your development site. Watch for current changes in the content in case you make some updates to the files and create a folder to serve the files through a server port. So now you can visit your site at ip-address:8000. You should see Hello World printed on the page in between header tags. To stop the server (as mentioned in the terminal), just run CTRL + C.

You’ll notice that inside the mysite/ folder, you now have another folder called output_dev/ in which the equivalent html files are stored. To generate the production files, add the --env=prod tag to the sculpin generate command:

sculpin generate --watch --server --env=prod

This will generate the output_prod/ folder and the necessary files inside. You can then sync this folder with your Apache so you can use a proper server to deliver the site pages to the browser. Let’s quickly see how to do that.

Assuming that you want the site to be accessible from out of your Apache’s default /var/www/ folder (the web server root directory), you can do the following. Navigate to the output_prod/ folder:

cd output_prod

And run the following rsync command to synchronize the files from here with the /var/www folder:

rsync -azv * /var/www

Now you can access the site straight from going to your VPS IP address (if you haven’t changed any virtual host configuration). And just run this command from the same folder whenever you make any changes to your site and generate new html files.

Sculpin uses Twig for its layouts, which is a powerful templating system for PHP. There is an introductory article about Twig on DigitalOcean. As we saw, what gets printed out on the page resides in the source/ folder - this is your content written in markdown. Let’s now create a layout into which that index.md file content will be injected.

Inside the source/ folder, create a folder called _views (the naming is a best practice kind of thing):

mkdir _views

Inside this folder, create a file called main.html. In here we can declare all the main page HTML we will want + the Twig content block which will render our site content. So for instance, paste inside the following:

<html>
<head><title>My first Sculpin site</title></head>
<body><div class="content">{% block content %}{% endblock %}</div></body>
</html>

Now edit the index.md file we created earlier, and instead of this:

---
---

# Hello World

Paste this:

---
layout: main
---

# Hello World

Now if you run again the sculpin command (you can leave out the watch for now):

sculpin generate  --server

You should see that the markdown file you wrote (index.md) is automagically injected in the Twig content block we defined in the main.html template, due to the YAML declaration we made at the top of the file. Neat.

If you want to see more about what you can do with Sculpin, you should get the Sculpin blog skeleton that can help you better understand how it works. You can use git for this:

cd ~
git clone https://github.com/sculpin/sculpin-blog-skeleton.git blog
cd blog

Now we need to have Sculpin install the project dependencies using Composer. So just run the following command:

sculpin install

Next, you can run the sculpin generate function with the server option and go back to the browser to see the blog site you just created. You can then explore the files that make up the blog and see how they work together. Additionally, you can add a new post to the blog. Go to the _posts/ folder:

cd source/_posts

And create a new file:

nano 2020-02-07-my-post.md

Paste the following inside and save:

---
title: My post
---

# Hello world.

Then go ahead and generate again and check out the blog. You’ll see your new post there.