So what is Pelican?
Pelican is a tool, written in python, for generating static html pages from restructuredtext and other markup languages.
If the first sentence of this article makes no sense to you, fear not, this tutorial for blog writing in Pelican is going to start from the absolute basics. When I started writing this blog, I had a little html experience but I was no web developer by any means. For a programmer, writing a blog using Pelican is a natural and very easy way to get to grips with hosting static html. The following instructions assume very little prerequisite knowledge; if you already have, say python, just skip that step and move on.
Creating a blog with Pelican is easy when you know how but if you're completely new to web development we will give a brief overview the purpose of each of these tools, how they're connected and how they'll lead to your shiny new blog.
The goal of all this is to generate HTML code, which is used for creating static websites. The benefit of HTML code is that your website looks exactly the same on any browser around the world. Great news. However, writing HTML is rather heavyweight if you're only interested in a little blogging.
This is where reStructuredText comes in, this is a simple what-you-see-is-what-you-get language, in other words, it requires minimum programming of any sort. reStructuredText is like writing any document, you just need to throw a couple of commands in for formatting. Pelican is an application (built on python) that turns your easy to write reStructuredText (.rst) files into all the HTML you need.
The only thing you need is a place to put your HTML files, so that they're available on the web. For this you'll need a way to host your files. Once you've done this, Pelican also provides scripts to automatically serve your HTML files to this hosting space. Interested? Does it sound too good to be true?
It's all true and the details are below, READ ON.
Python is a multi-purpose, high-level programming language, if your any sort of programmer, you would have heard of it even if you haven't used it. Blogging with Pelican doesn't require knowledge of python syntax but it will help if you come across any errors in the process. Go to the python beginners page for a good starting point.
Even though we won't be coding in python, we will need it to execute Pelican, which uses python. So if you haven't got yourself a copy, head over to Python for the installation details for your platform (v2.7 will be fine).
A brief apology to windows users, the rest of the guide will focus on Linux and OSX systems.
Python comes bundled with a number of built in packages with an abundance of exciting features but there is more. PIP is an application to help you to install, uninstall and track your python add-ons.
Downloading pip will also lead you to running your first python script! Head over to the pip website and download get-pip.py. The .py extension is used for python scripts, so we just need to run this script, head over to your terminal and type:
$ python get-pip.py
Linux users may use apt-get, equivalently Macports or Homebrew for OSX users.
Now we have pip, we have all we need to get the Pelican add-on for your python set-up but DON'T. This is a good time to start using the virtual environments for python. As I mentioned earlier, there are so many packages available for python (many of which can be installed with pip), sometimes they conflict, or cause problems. It is a good idea to have an environment where you can run python with specific add-ons. Don't worry if this all sounds a little complicated, we'll learn through building an environment for Pelican.
First use pip to install virtualenv (it may also install a number of other packages that virtualenv requires):
$ pip install virtualenv
We can then create an environment in which to store our specific python set-up for running pelican. I keep my environments in my home directory, to do the same you would run:
$ mkdir ~/virtualenvs $ virtualenv ~/virtualenvs/pelican
This command has now setup a new version of python and pip in ~/virtualenvs/pelican; this directory also has an activate script which we can use to turn a specific terminal session into one that uses our pelican python setup:
$ source ~/virtualenvs/pelican/bin/activate
Now your terminal will use your pelican python build whenever you call python or use pip for installing. Remember that this only happens in your current terminal environment; if you close it down, you will have to use the source command again.
If you've made it this far, you'll be cruising through the rest of this guide, so read on! Install Pelican through pip, making sure that you are in your pelican virtual environment.
$ source ~/virtualenvs/pelican/bin/activate $ pip install pelican
Since our pelican virtual environment is brand new, it won't have any of the additional packages that Pelican requires; so you'll probably see quite a few additional things installed through pip.
Now you have Pelican ready to go, we can start writing some reStructuredText and translating it into HTML, very exciting. If you're anything but a complete expert, then I would strongly suggest using the quick-start option.
Pelican provides a very handy tool pelican-quickstart that truly does what it says on the tin. It will create a directory structure, some basic files and a couple of scripts that will be vital for developing your blog. So lets take look: go into your new project directory:
$ mkdir ~/path/to/project $ cd ~/path/to/project $ pelican-quickstart
The quick start guide will ask you the following questions, I have included some descriptions to help you make the right choice and suggestions if you're not sure.
- Where do you want to create your new website? A: just give the project directory, or hit enter to use the current one (as in the code above)
- What will be the title of the website? A: The main title
- Who will be the author? A: Default author name
- What will be the default language? A: Hit enter for English or type another, this is particularly important if you plan to make use of multiple language options.
- Do you want to specify a URL prefix? A: If you already have hosting space and a link to your website, you can enter that now, hit no otherwise. Even if you do, you do not have to enter it now, it's only for later convenience.
- Do you want article pagination? When you create your blog, the default landing page is an index of your article titles. Enabling pagination means that this index is seperated over multiple pages, helpful for larger projects. I would suggest setting this to no, for now, as you can configure it later as your index grows.
- Do you want to generate a Makefile? A: Absolutely yes, this Makefile will be your ultimate ally whilst writing up the blog.
- Do you want an auto-reload and simpleHTTP script? Again, this is pretty helpful, go ahead and press Y.
- Now you will be asked whether you want to set up (another!) automatic script to upload your finished HTTP files to your hosting space. If you do have somewhere to put them, then you'll probably know how you want to transfer them; hit yes on your preference and enter the details. You can choose from: FTP, SSH, Dropbox, S3, Rackspace, GitHub.
You are all set so lets see what we've got.
You are now faced with a directory of files, at first we are interested in filling the content directory, this is where your reStructuredText files are going to go. At this stage, I'm not going to get into how to write up a reStructuredText article but why not try going ahead and copying this first post into your content directory as ~/path/to/project/content/firstpage.rst:
My first post ############## :date: 2014-09-19 12:00 :tags: testing, firstpost :category: Tests :slug: my-first-post :authors: Joe Bloggs :summary: This is my first ever article So here we are, writing in your first ever blog post, fun and excitement abound in this place.
Now we can use Pelican to turn our single .rst file into a HTML file. Head back to your project directory and use the Makefile provided with the target html:
$ make html
This will create all the html files needed, using default settings, colours and themes. Sounds boring but get ready to see how quickly you have just thrown together a website. You can peek in ~/path/to/project/output to see all of the output generated, which will make you feel productive.
The quick-start also provided a script for running a local server, so we can experience our website as it would look online but from our own machine! Use the following command:
$ make devserver
This will continuously update your HTML output as you edit your content files and then serve the HTML output to http://localhost:8000. If you type that in to your favourite browser you get to see the output, CONGRATULATIONS!
To stop the server run
$ ~/path/to/project/develop_server.sh stop
Now get over to the Pelican help pages to learn how to write your content, change themes, colours and settings.