This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:
Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.
See Instead: This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.
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.
Sculpin is an interesting static site generator that uses markdown for quick content formatting and Twig for awesome templating to get you deploying a static site easily. We’ve seen what a project looks like and how to get started, as well as what an already made blog site built with Sculpin looks like.
<div class=“author”>Article Submitted by: <a href=“http://www.webomelette.com/”>Danny</a></div>
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Great tutorial! This was pretty helpful for someone who has never setup a sculpin project before. I ran into a few issues in the beginning, turns out my system (Mac OSX 10.9.4) has issues with its version of PHP not having default timezone being set. More about that here: https://github.com/sculpin/sculpin/issues/84