This is the first article in a series about setting up my own website using a Static Site Generator. For other articles in the series, click on the title of the article under the heading “Static Site Generators” on the right side of the webpage.
Introduction¶
Why do I want a static website?
It has been on my mind for a couple of years that I would like to talk about some of the things that I find cool and other things that I feel strongly about. As a big proponent of servant leadership, I want to help and inspire people to do more, be more, and help more.
Basically, I want a low-friction, easy to use platform that allows me to communicate with and help others in my own way. I also want tooling and workflows to be efficient so that I can spend more time communicating and less time fidgeting on the website.
To this end, I want to focus on something that is simple, but extensible. I want to be able to have a good mix of my own pages and a blog, allowing for flexibility on what I am doing. I want to be able to focus on the message and my voice, rather than the medium.
From my research, Static Site Generators fulfils those requirements in spades. But as with a number of things I do, I want to take the time to determine if they are the right choice for my website, and if so, select the right one for me. I would rather take a small amount of time now to ensure it is a good fit, than to take time reworking things because it wasn’t.
What are Static Site Generators?¶
Static Site Generators (SSGs) are programs that take a certain type of website and shift the heavy loading of the website from the content-request point to the content-update point. Put another way, the decision of what content to show the viewer of the web page is changed from when the web page is requested by the browser to when the web page content is updated by the author. Therefore, to be eligible to use a SSG for a given website, that website must have all its content available when the content is updated, with no real time content present. There are small ways to get around that restriction, but those present their own challenges. As such, I am going to assume that 95% of the website is going to be static, and that all the important information is within that 95%.
SSGs themselves usually combine different technologies to achieve their results: writing, templating/styling, metadata, and publishing. The pages for the site need to be written in either a supplied WYSIWYG editor or in some format like Markdown. Once the pages are written, generic styling and templating are applied to the collection of pages to make sure that the branding on the pages is consistent. To help organize the pages, most SSGs include some form of metadata that is attached to the pages, used by the SSG to group pages and provide other guidance to the SSG itself. Finally, when the pages are checked over, there needs to be a simple way to publish them to the intended website.
Reducing the barrier to entry and keeping it low is essential to a SSGs success. Therefore providing multiple technology choices for parts of the SSG is common. All the SSGs that I looked at had a variety of options for most of these technologies, with templating and styling being the exception. In the case of templating, most of the SSGs support a single default templating engine that is used on all the pages. With respect to styling, common HTML technologies such as Cascading Style Sheets (CSSs) are most commonly used. Besides keeping the cost of the templating and styling low, using a common technology allows for lots of examples to be provided by the Internet at a low cost.
Is a Static Site Generator The Right Choice For Me?¶
In determining whether SSGs are the right technology for my site, I started making a list of the things I was primarily worried about with a website:
-
Security
As I deal with security concerns at work, this one was top of mind. How often have I heard about various platforms and websites being hacked in the last month? To avoid this, I want to keep my website as simple as possible. Static pages created by a SSG leave a single attack vector: the repository where my website’s HTML pages are being stored.
Mitigating attacks by only having a single attack vector is very attractive solution for me.
-
Ease Of Use
I don’t want to be messing with the website more than I have to. I either want to be updating something on the site in response to something I am working on, or working on that thing. I am already used to writing documentation at work in Markdown, so writing web pages in Markdown is already very efficient for me. In a similar manner, at work I keep documentation in a version control system, so keeping the pages in their various stages of completion in a readable form in version control is also efficient.
Using my already existing workflows, with minor modifications, is an acceptable solution that keeps ease of use high.
-
Real-Time Contents and User Input
A lot of my focus at work is making sure that we can anticipate and plan for events that happen to change our system’s state. If a user or another system sends a request to our system, can we validate the request, verify the system is in a good state for the request, and enforce the correct behavior for the response? Any good SSG takes care of this issue by eliminating any change of state.
Resolving the concerns of state management by removing all state information seems like an ideal solution for the limited scope of my personal website.
Once those were out of the way, only the big question remained: Do I have any plans for a web site that would require it to support dynamic content? My primary purpose is to allow me to communicate to interested readers. As such, the sites’s content is largely going to change only when I write something new and publish it. Based on the 95% barrier I set for myself above, such content appears to be will within that barrier.
To handle the remaining 5%, I am fine with any dynamic content for my site being generated using JavaScript. A good example of that is using something like Disqus for dynamic comments. By handling such things with a Javascript approach, I can keep the simple things simple, only making things more complex when they need to be. To me, that seems to be a solid way to handle the few exceptions that may arise.
For those reasons, I believe an SSG is an ideal choice for a personal website with a blog.
Which One to Choose?¶
In case I need or want to do any extension work, I want the SSG to be in a language I am comfortable with, maintaining the ease of use concern from the previous section. At the moment, that limits the SSG language to C#, Java, and Python. While I can work effectively in other languages, the comfort and enjoyment levels are not there. As I am doing this for myself, I want the writing of any extensions to be easy and fun to increase the chances that I will stick with the writing and the SSG choice.
Looking at a number of sites, these are the SSGs that appear the most.
| Generator | Language | Website | Last Updated |
|---|---|---|---|
| Hugo | Go | https://gohugo.io/ | May 30, 2019 |
| Pelican | Python | http://blog.getpelican.com/ | May 13, 2019 |
| Hexo | Node.js | https://hexo.io/ | Jun 6, 2019 |
| Jekyll | Ruby | http://jekyllrb.com | Jun 9, 2019 |
| Gatsby | NodeJs | https://github.com/gatsbyjs | Jun 9, 2019 |
(Note that the last updated column is current as of 2019-Jun-09.)
Given these goals in mind, I looked through the choices for static site generators and decided to go with Pelican. It’s written in Python, has been maintained recently, any extensions are written in Python, and seems to be easy to use. This choice supports my desire to write pages and articles in Markdown, and any needed extensions can be tweaked if needed.
What Was Accomplished¶
At the beginning of this article, I was intrigued by Static Site Generators and whether or not SSGs would be an effective tool for me to communicate through. During the article, I not only determined that it was the right fit, but selected the Pelican as the SSG to use, based on its Python coding and recent updating.
I feel that this determination to use SSGs, and Pelican specifically, puts me in a good position to start building my website with confidence.
If You Are Trying To Decide…¶
If you are trying to decide if SSGs, or a specific SSG, will work for you and your site, I would encourage you to walk through a similar process to what I did. Figure out your own concerns for your own website, and determine whether or not an SSG will address those concerns. If you think you may write extension for it, take a look at the language of the SSG and make sure you are familiar with the extension language. Most importantly, figure out whether your choice of SSGs in general or a specific SSG will serve as a tool for you to publish your information, or whether it will be an impediment to you publishing.
From the point where I was at when I made the decision, Pelican appeared to be a good choice for me. I did some research to make sure this was the right choice for me. Make sure you ask yourself those questions, get those answers through research, and make sure your choice is going to work for you!
What’s Next?¶
Next, I need to start exploring Pelican and how to set it up with default content. This will be covered in the article Setting Up the Pelican Static Site Generator.
Comments
So what do you think? Did I miss something? Is any part unclear? Leave your comments below.