Using Pelican - My Simple Guide

Since I just started using Pelican to generate the code for this site I thought it would be good to write a guide on how I did it. This may help others, but more importantly it will help me as months or years from now I look back on this work.

Requirements

First step to any good deployment is knowing your requirements. In my case I had several that needed to be met for me to move forward.

Here are a list of my requirements for moving gowen.net from a php site to an html site.

  • Want to get away from dynamically scripted web page formats such as php and need an easy way to generate static html pages.
  • Need to be able to write, generate, and publish site content from a number of devices including Windows and Linux platforms.
  • Want to be able to host the site in an Amazon AWS S3 bucket and need a method to publish there.
  • Need a generator that uses Python (my new main language) so I do not have to install Ruby or something I wont use for anything else.
  • Want to write site pages in markdown syntax and need a generator that supports that.
  • Need a generator that supports page content as well as blog content.

Applications and Services

Pelican is ultimately the static site html generator I chose. However, it had several application dependencies that needed to be satisfied as well.

In addition, my requirements determined that other applications and services would also need to be utilized.

Here is the list of applications and services I needed to have available to make this happen.

Services

  • Amazon AWS S3 bucket for the published site
  • Github repository for the artifacts to be used in generating the site

Applications

  • Python 2.7.x - Programming Language available via .deb and .exe installations
    • Linux Install (debian based)
      • sudo apt-get install python2.7
    • Windows Install
      • Navigate to Python Windows Downloads and download the appropriate installer
      • Execute the installer which should install Python on your system along with a Python enabled powershell instance.
  • Pip - This is bundled with Python but may need to be updated
    • pip install --upgrade pip
  • Pelican - Can be installed via Pip
    • pip install pelican
  • Markdown library - Python implementation of Markdown
    • pip install Markdown
  • Typogrify library - Python text transformations for improved html
    • pip install typogrify
  • Git - Version control system available in most distribution repositories (used to access Github)
    • Linux Install (debian based)
      • sudo apt-get install git
    • Windows Install
      • Navigate to Github Desktop and download the installer
      • Execute the installer which should install the Github Desktop GUI along with a Git enabled powershell instance.
  • S3cmd - Linux CLI S3 tools (used to publish to Amazon AWS S3)
    • Import S3tools signing key:
      • wget -O- -q http://s3tools.org/repo/deb-all/stable/s3tools.key | sudo apt-key add -
    • Add the repo to sources.list:
      • sudo wget -O/etc/apt/sources.list.d/s3tools.list http://s3tools.org/repo/deb-all/stable/s3tools.list
    • Refresh package cache and install the newest s3cmd:
      • sudo apt-get update && sudo apt-get install s3cmd
  • S3browser - Windows GUI S3 tools (used to publish to Amazon AWS S3)
    • Navigate to S3browser Download and download the installer
    • Execute the installer which should install the S3browser GUI application
  • Atom - Cross platform text editor with markdown syntax highlighting
    • Linux Install (debian based)
      • wget -O ~/atom-adm64.deb https://github.com/atom/atom/releases/download/v1.6.2/atom-amd64.deb
      • sudo dpkg -i ~/atom-adm64.deb
    • Windows Install
      • Navigate to the [Atom Downloads] page and choose to download AtomSetup.exe
      • Execute this installer which should install the Atom GUI application

Initial Setup

To get started using Pelican we first must build the skeleton framework it will use.

To do this we simply execute the following command:

pelican-quickstart

This will ask several questions about our site and then create a directory structure for it along with the configuration files it needs.

Creating Some Content

Within our new site directory there will be a subdirectory named content that will house all of our site content.

It will be blank at first creation but we can fill it with markdown files that will become articles in a blog fashion.

We can also create a subdirectory within content named pages where we can store markdown files that will become normal non-blog web pages that are automatically incorporated into a menu.

Generating The Site

Once we get all of our markdown files created we can see how it looks by generating the site and viewing it in a browser. This command will generate the site:

pelican /path/to/your/content/ [-s path/to/your/settings.py]

Simply tell Pelican where your content is and it will spit out an html formated site from it in a subdirectory named output. The settings file does not need to be specifically added to the command if you are using the default filename from the quickstart.

Now we can load this output directory in a browser using the file:\ method or a nicer approach is to spin up a local web server. Lucky for us one comes bundled with Python. Do the following to start the local webserver:

cd output
python -m SimpleHTTPServer

Now point your browser at http://localhost:8000 and you will see your site in all its basic theme glory.

Saving Work To Github

Without going into too much detail on how git and Github work I'll just say that this is a good point to push your whole Pelican site working directory into a Github repository.
This will allow you to pull these files from any of your devices to make changes in the future.

One thing to note is that you will want to tell git to ignore some files in your Pelican site working directory before you push it to Github.
Specifically we want to ignore the output directory as this is just the generated html that will be posed on AWS S3 and does not contain anything we will modify by hand.
Also, you may want to ignore compiled python code ending in .pyc that is created from executing a .py file.

This can all be accomplished via a single file named .gitignore.
Create the .gitignore file in the Pelican site working directory (the one that contains the pelicanconf.py file and content directory) and add the following text to it:

# Compiled Source
*.pyc
# output files
/output
/output/*

This will prevent git from pushing these files and directories to Github.

Adding and Modifying Themes

Pelican uses themes to change the look and feel of the web sites it generates. These themes are a collection of templates and css and js and images and more that will bring a static site to life. You can feel free to create all these on your own from scratch or you can download a theme and modify it to suit you.

Pelican themes can be previewed on the Pelican Theme Site where you can find one you like. Or you can clone their entire theme repository from Github using the following command.

git clone --recursive https://github.com/getpelican/pelican-themes.git

Either way you can find a theme you like and then customize it to work for your site.

Publish the Site to S3

Once you get everything looking the way you like it is time to publish your site for the world to see.

If you need to change something about your site generation for production versus the local copy you have been previewing this can be done by using a seperate production configuration file.

Simply generate the site again using this different configuration file and it will include all your production changes (like site url settings). In my case this was not necessary so I am just going to publish the same output directory I preview to my production site.

In order to publish to an Amazon AWS S3 bucket you must first set that up in your AWS account. Amazon has a Good Reference Page explaining how to do this. Assuming this has been done and you have set up your S3tool with your AWS authentication keys you are ready to publish your site.

Linux S3 Publish

On a Linux system the s3cmd command line tool will be used to publish your site to S3. From your Pelican site working directory type the following command:

s3cmd sync ./output/ s3://your.bucket.name --acl-public --delete-removed --guess-mime-type

That's all there is to it. Your site has been published to S3.

Windows S3 Publish

On a Windows system the S3browser graphical tool will be used to publish your site to S3.

From the S3browser application choose the S3 bucket you want to use and choose the option to mount it as a Windows drive.

Now you can use Windows Explorer to simply copy the files from the output directory to this S3 bucket.

That's all there is to it. Your site has been published to S3.

Conclusion

While what I have presented here may seem like a lot of work, it was actually all quite easy and quick to complete.

The final product is a system that I can use to easily keep my site content up to date.

The main benefit of a static html site is removing all the overhead of patching a web server constantly or being prey to hacks.

For me this was a quick and easy win.