Setting up this blog was shockingly easy thanks to the tools and documentation available. Sarting from scratch, it took me just over one hour to get the blog up and running with the two previous posts. Since then, I changed the theme, got comments working with Disqus, and personalized some of the links. Here is a step by step guide that should take an hour or two to get your own blog running. You should have some familiarity with python, github, and the command line; but you certainly don't need to be an expert. If I can do it, anybody can.
Get Python¶
If you are reading this blog, chances are you are a regular user of Python, but, if you don't already have Python installed, you'll need to get it up and running since some of the other software depends on it. If you are on Windows, Anaconda is great. I set this blog up from my Linux laptop where I also have the Anaconda distribution installed.
Get Pelican¶
Pelican is a static blog generator that made setting things up incredibly easy. I learned about it after stumbling upon Jake VanderPlas's blog. Simply download and install Pelican using Python's built in package manager, PIP. At the command line, type: pip install pelican. You can also install the other packages Pelican depends on with PIP, the most important of which is Fabric (which we will use later to create the site). If you know what you are doing, you can also install pelican into its own virtual environment, but this is probably unnecessary for most people. There is a terrific getting started guide for Pelican that helped me a lot.
Setup Your Site¶
One of the best parts of Pelican is its quick setup utility, but you will need to have thought about your webhost before running it. If you want to use ftp or other similar protocols, you'll want to have that all set up and ready before using the quickstart utility. Since I am using github, I manage uploading the site to the server through git. Create a folder for your blog and open it up at a command prompt. Now, type pelican-quickstart and answer a few questions. The quickstart utility creates a file structure and the necessary configuration files. The most important thing is to answer 'yes' when it asks whether you want it to creat a makefile and Fabric file for easy site generation. This option will make your life much easier.
Pelicanconf.py - Making the blog yours¶
Most of the important tweaking you will do to the look and feel of your blog is done in the pelicanconf.py file that the quickstart utility created. This is where you set the theme, create links for your sidebar, and generally manage the aesthetics. The most important thing to remember is: DO NOT SET YOUR SITE URL IN THIS FILE. Your site URL is set in the publishconf.py file, and setting it in the pelicanconf.py file will break your site.
To use the octopress (or any theme), create the following line in pelicanconf.py: THEME="/path/to/your/themes/pelican-octopress-theme" In general, changing the theme is as easy as changing this line to your theme of choice. More information on themes is below.
Generate Content¶
To create a post, just start a markdown or reStructured text document in your favorite text editor. Pelican makes heavy use of metadate to generate the site, so each post needs a header with the appropriate information. I prefer markdown, so the metadate for my first post is:
Title: The First of many, maybe
Date: 2013-11-21 20:30
Tags: python, science
Category: miscellaneous
Slug: first
Author: Adam StevensonOnce you are done with the post, put it in the content folder created by the quickstart utility.
Create HTML and Publish¶
With your new post in the content folder, simply open your blog's folder at a command prompt and type fab build. If there are not any major errors, you can then type fab serve and check out your blog at localhost:8000 in your browser. If you are happy with it, type fab publish to produce the final version that you should upload to your webhost. If you did not use the automatic ftp (or whatever) settings during the quickstart, now you simply upload the contents of the 'Output' folder to your webhost. If everything went well, your blog should be up and running.
Comments with Disqus¶
There is a Pelican plugin for Google+ comments, but I found Disqus to be much easier to get working. With the octopress theme, you simple sign up for an account at disqus.com and paste the sitename it gives you into the appropriate field at the end of your publishconf.py file. Be sure to uncomment the line, if you want it to work.
Ipython Notebooks¶
There are two ways to get Ipython notebooks to work with your blog. The first one I used was the pelican-ipythonnb plugin. With the github repository cloned to your local drive, follow the instructions in the repository's readme. For me, it worked easily the first time.
The other option is to use the liquidtags plugin, but I have not tried it out yet.
Get Add-ons¶
The default setup used by Pelican is not bad at all, but its nice to have all the extra bells and whistles like plugins and new themes. Github is the central repository for Pelican, and you should clone the pelican-plugins and pelican-themes repositories to get a lot of options. If you want to use Ipython Notebooks with your blog, you should also clone the pelican-ipythonnb repository.
If you are not too familiar with github, the process for cloning a repository is:
(Linux)
- Log in to github and navigate to the repository
- Click on the 'Fork' button in the upper left hand corner
- Use git to clone the repository with the command
git clone https://your_user_name/repository_name
On Windows, there is a GUI based program that makes cloning repositories very easy.
In the pelican-themes repository, you will find lots of good options and you can see most of them here. For starting out, though, I highly recommend the octopress theme available in the pelican-octopress-theme repository on github. It looks good, and everything seems to work perfectly, right out of the box.
Pelican also has its own theme management system, but I did not use it.
Conclusion¶
At this point, you should have a working blog, and it probably took less time than it took to write this post. Hopefully, this guide was reasonably complete and easy to understand. If you have comments, suggestions, or questions, please leave them below and I will try to update as needed.