Static Websites with Sculpin

by Stephen Cross


Posted on Aug 15th, 2018


sculpin

This blog, on 8/14/18, is static HTML generated by Sculpin, a static site generator written in PHP. Sculpin converts Markdown files, Twig templates and standard HTML into a static HTML site that can be easily deployed.

What is a Drupal guy doing with a static HTML website? Truthfully, just tinkering with technology. I like the idea of simplifying and minimizing. For simple blog, is it necessary to have a sophisticated content management system using a database and generating a website dynamically? That's the question I'm exploring with Sculpin.

Why Scuplin? There are many frameworks available for generating an HTML website, the most popular is Jekyll, like Sculip, it’s open source, but built on Ruby and Liquid. Sculpin is a built on PHP and Twig, which pairs nicely with my Drupal experience. It was an easy decision to start with Sculpin. I may take a look at other Ruby and Python options in the future.

I’m not a Sculpin expert, but I'm learning. I downloaded the sample blog implementation to use as a working reference. Following the Sculpin Getting Started instructions, I quickly had the sample website running on my local computer. After looking through the sample website code and documentation I started a new website. I used a simple bootstrap theme, converted it to TWIG and had my blog running in a few evenings.

Sculpin Basics

Content

Content resides in a markdown files (.md). In my blog implementation, the content is either a blog post or simple page. In Drupal terms, this content is known as an Article or Basic Page. To create a new blog post, I simply create a new markdown file with some meta data at the top of the file. The example below is a blog post with meta data.

---
title: At home on July 4th
author: Stephen Cross
tags:
    - Life
primary_image: /images/blog/home_primary.jpg
primary_image_alt: Mantle with patriotic HOME sign
list_image: /images/blog/home_list.jpg
list_image_alt: Mantle with patriotic HOME sign
---

It's July 1st.  In most parts of the US, that means three days until a day off to celebrate the nations birthday.  In Bristol RI it has a very different meaning.  The 4th of July is a significant event, it's THE event.   Planning for July 4th, starts on July 5th the previous year.   The celebration begins in June and climaxes with the oldest parade in the country.   

...

We are days away from our second 4th hosting.   It's exciting to have family and friend join us for this purely American, hometown celebration.  

Happy 4th.

Templates

Sculpin uses Twig for a templating engine. Twig is straight forward and there is an abundance of references on-line.

Generate

When your templates are setup, and you have some content, you then generate the website. Scuplin use the markdown and templates to output a stand alone HTML website.

vendor/bin/sculpin generate

Sculpin also provides a web service to view your website locally as you work on it. The command below kicks off the service, which monitors your source code and automatically refreshes the HTML as you update markdown and templates. I can view the website at http://localhost:8001.

vendor/bin/sculpin generate --watch --server --port=8001
Detected new or updated files

Generating: 100% (221 sources / 0.00 seconds)
Converting: 100% (232 sources / 0.08 seconds)
Formatting: 100% (232 sources / 0.01 seconds)
Processing completed in 0.13 seconds
Starting Sculpin server for the dev environment with debug true
Development server is running at http://localhost:8001
Quit the server with CONTROL-C.

Deployment

When development is complete, you generate HTML to a new folder, /output_prod:

vendor/bin/sculpin generate --env=prod

You can then push the HTML to the webserver with an scp or rsync.

rsync -avze ssh  output_prod/ user@website.com:/var/www/html --delete

Workflow

After the website is built, the daily workflow is:

  1. Create new post in a markdown file, ie. _post/2018-08-01-Hello-World.md
  2. Generate HTML
  3. Push HTML to Server

For me, these are manual steps, but I plan to change this workflow to use a continuous deployment strategy. As I push updates to my git repo, the HTML will be automatically generated and pushed to the server.

Benefits

Although I've recently started using Sculpin and my knowledge is limited, I see the benefits as:

  • Performnace - HTML websites are super fast.
  • Low powered production server - The website can run on almost anything. The only runtime requirement is a web server. It have StephenCross.com running on the smaller Digital Ocean VPS with only apache install. I look forward to trying a Rasberry PI.
  • Low maintenance - I don't have to worry about frequent stack updates.
  • Backup - While I'm backuping up the server weekly, it's not necessary. The content and tools are on my local computer and in a git repo.

Cons I haven't found many drawback yet. I do find the documentation sparse with few online examples and resources.

Next Steps

I see the next steps as:

  • Implement a CI process
  • Implement a search mechanism
  • Add sidebar to view by category

Check back for updates!

Resources


Comments


Tags: Tech, Drupal

NEDCamp
New England Drupal Camp is on November 16 & 17. 2018 at Rhode Island College.
Talking Drupal
A podcast about web design and development by a group a guys with one thing in common, they love Drupal.
This Website
This website is an experiment. It's built with Sculpin, which is a static site generator written in PHP. It converts Markdown files, Twig templates and standard HTML into a static HTML site that can be easily deployed. Learn more about this website build.