Welcome to the first installment of "Making This Site". In these articles, I will describe the exact steps I went through to build this website. At the end of every article is a link to a commit on GitHub showing all the code that was added.
The purpose of this website is hosting various projects I work on. The requirements are simple. I would like:
With these requirements in mind, I set out to find a suitable static site generator (SSG). After reading about the pros and cons of many different static site generators I decided on Pelican.
My decision to use Pelican was primarily based on my pre-existing knowledge of Python and the fact that Pelican had almost all the features I thought I would need and not much more.
For reference I am using Pelican 3.7.1 and Python 2.7.11 on Mac OS 10.12.2
Setting up Pelican is quite simple, I followed the quickstart- guide to get get going.
pelican-quickstart generates a skeleton site with a default theme. By the end of this article I will have a site that could, theoretically, go online.
Here are the options I used to generate my initial site:
$ pelican-quickstart Welcome to pelican-quickstart v3.6.3. This script will help you create a new Pelican-based website. Please answer the following questions so this script can generate the files needed by Pelican. > Where do you want to create your new web site? [.] . > What will be the title of this web site? Jared Andrews > Who will be the author of this web site? Jared Andrews > What will be the default language of this web site? [en] > Do you want to specify a URL prefix? e.g., http://example.com (Y/n) Y > What is your URL prefix? (see above example; no trailing slash) http://jaredandrews.com > Do you want to enable article pagination? (Y/n) n > What is your time zone? [Europe/Paris] Boston Please enter a valid time zone: (check [http://en.wikipedia.org/wiki/List_of_tz_database_time_zones]) > What is your time zone? [Europe/Paris] America/New_York > Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) Y > Do you want to upload your website using FTP? (y/N) N > Do you want to upload your website using SSH? (y/N) N > Do you want to upload your website using Dropbox? (y/N) N > Do you want to upload your website using S3? (y/N) N > Do you want to upload your website using Rackspace Cloud Files? (y/N) N > Do you want to upload your website using GitHub Pages? (y/N) N Done.
To see the skeleton site I run
develop_server reloads the site as files are changed
providing a tight feedback loop when making updates.
After seeing the skeleton site I decided to write the article you are
reading right now. Pelican provides the option to write articles in
Markdown and a number of other languages. I decided to use Markdown,
the default option. In the root directory for your site you will find
content directory. This directory is where you store your
To make this article I used the following command:
$ touch content/pelican_00_setup.md
Once the file was created I opened it and wrote this article. An article file needs metadata. The metadata for this article looks like:
Title: Making This Site, Part 0: Setup Date: 2015-11-01 10:02
Each post can also have a single category and a list of associated tags. Underneath the title and date information in the Markdown for this post I have also included:
Tags: programming, web-dev, pelican Category: making-this-site
Each post can have a single category. I imagine that typically I will only use categories when I want to group specific posts together, for example, I would want a visitor of this site to be able to to view all of the "Making This Site" posts in one place, thus I have created the
Tags are additional metadata that can be used to find related posts. Typically I will provide a very general tag and then a couple more specific ones.
After the metadata you start writing the content of the article. You can view the complete markdown file for this article here.
For this article I used a number of Markdown features within the text.
* creates a bullet point.
# indicates that the line is a header. I also prefaced lines of code with at least four spaces so they would be shown in a code block.
At this point, with very little effort, I have a working blog with one article on it. Now I want to make it look good. Next, I will develop a custom Pelican theme.
To view this site the way it looked once all the changes described in this article were made, click here.
Changes on GitHub.