Writing a blog can be done in many ways, and there is lots of software available to help you set up the perfect blog for you. A popular piece of software is Wordpress, for which many themes and plugins are available. Together with a lot of information about it on the web to get you started. It’s pretty easy to use once it’s all set up and ready to go, from a user’s point of view.
A downside of Wordpress is that it is a bit more work to install and configure on your own. It is database-driven and is dynamic in nature, so requires MySQL and PHP. These add complexity when you want to host it yourself. This in turn requires you have to keep more software, including Wordpress itself, updated to remain as safe from exploits as possible.
Within the community of IT-minded people there seems to be a trend of moving to static pages. Those are simple, easy to host and also faster as a bonus! And they do not require you to run a database or set up PHP for your web server software. But does that mean you have to resort to writing your own HTML and stylesheets? Not at all!
Nowadays many generators exist for creating static sites. A popular choice seems to be Jekyll combined with Octopress, which calls itself “a blogging framework for hackers”. Sound pretty neat, but Ruby is not a language I’m fluent in, nor do I have it installed on my system. So not really my cup of tea.
Then I bumped into two others: Pelican and Felix Felicis (also called
liquidluck). Both written in Python, which I can somewhat read, and have installed on my system already. Both can look great and seem to have a comparable feature-set. I’ve read that Felix Felicis seems to have faster page generation, but I haven’t really tested that myself. Felix Felicis seems to be a younger project, as I couldn’t find as many blogs made with it as I could find ones made using Pelican. The same goes for documentation on setting up and using the software. And as Pelican seemed to be able to satisfy my needs when it comes to a blog, I went with that.
Installing Pelican is not very difficult. But having experience working with packages and perhaps Python can come in handy. I’m not exactly a Python wizard myself, I can just read the language and fiddle with it from time to time. But if you do not know it at all, that’s not a problem either. For this HOWTO I will set up Pelican on my laptop, which runs Debian GNU/Linux Wheezy.
Because Pelican is written in Python, it requires that to be present on the system. And to install Pelican itself you want to use the Python
pip tool for installing/managing Python packages. Using
easy_install is also supported and you could also download the source code and use that if you want. But using
pip makes it really easy.
So let’s install
$ sudo aptitude install python-pip
aptitude for your package manager.
apt-get would also work here, I just happen to like
We will install
pip which will install
virtualenv along with it as a dependency:
$ sudo pip install virtualenvwrapper
Once that’s done we need to make some changes to our environment so we are able to use
We need to tell the shell to set a couple of variables and execute the
virtualenvwrapper script on start. When you use Bash as your shell, the default on pretty much any GNU/Linux distribution, you should edit your
.bashrc and add the following lines:
export WORKON_HOME=$HOME/.virtualenvs export PROJECT_HOME=$HOME/proj source /usr/local/bin/virtualenvwrapper.sh
WORKON_HOME directory is where
virtualenvwrapper places your virtual environments. You do not need to create it, because
virtualenvwrapper will create it automatically if it does not exist. The
PROJECT_HOME directory is where
virtualenvwrapper places project working directories. Your Pelican blog will end up in there, so this is a directory of interest for you. I called mine
proj (short for projects) and created it.
$ mkdir ~/proj
Now you should either reload your shell or ask your shell to read it’s configuration file once more. When using Bash this can be done as follows:
$ source ~/.bashrc virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/initialize virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/premkvirtualenv virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postmkvirtualenv virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/prermvirtualenv virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postrmvirtualenv virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/predeactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postdeactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/preactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/get_env_details virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/premkproject virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postmkproject virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/prermproject virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/postrmproject
If you edited and reloaded your shell configuration file, your output should be similar.
Create a new project
You are almost ready to install Pelican in a virtual environment. But we still need to create that virtual environment. Let’s do that now.
stefan@aether:~$ mkproject blog New python executable in blog/bin/python Installing setuptools............done. Installing pip...............done. virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/predeactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/postdeactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/preactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/postactivate virtualenvwrapper.user_scripts creating /home/stefan/.virtualenvs/blog/bin/get_env_details Creating /home/stefan/proj/blog Setting project for blog to /home/stefan/proj/blog (blog)stefan@aether:~/proj/blog$
Notice how my prompt changed to include the name of the project we just created? You are now in a subdirectory with the name of your project (blog) inside the PROJECT_HOME directory you specified before. Ready to install Pelican in the virtual environment.
Install Pelican using pip
Let’s not wait any longer and install Pelican already:
(blog)stefan@aether:~/proj/blog$ pip install pelican
pip will now go to work, downloading Pelican and any dependencies and installing them in your virtual environment.
These dependencies consist of
six on my system.
I will also install another package: Markdown. Pelican supports this markup language and I write this blog in it. It’s also possible to use reStructuredText which is available by default. I haven’t used that much myself, perhaps I will in the future, but at the moment I use Markdown.
(blog)stefan@aether:~/proj/blog$ pip install Markdown Typogrify
Hurray! Pelican is now installed on your system. Ready to start configuring it, so you can start using it for your blogging pleasure. To help you with this, Pelican includes a program that starts with a short questionnaire, and sets up the current directory for Pelican with your configuration.
(blog)stefan@aether:~/proj/blog$ pelican-quickstart Welcome to pelican-quickstart v3.1.1. 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. Using project associated with current virtual environment.Will save to: /home/stefan/proj/blog > What will be the title of this web site? sjoosten.nl > Who will be the author of this web site? stejoo > 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://sjoosten.nl > Do you want to enable article pagination? (Y/n) > How many articles per page do you want?  > Do you want to generate a Makefile to easily manage your website? (Y/n) > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) > Do you want to upload your website using FTP? (y/N) > Do you want to upload your website using SSH? (y/N) > Do you want to upload your website using Dropbox? (y/N) Done. Your new project is available at /home/stefan/proj/blog
As you can see, it asks for some basic information. I left a lot of them at the defaults. Partly because I haven’t figured out what I really want some of them to be, and I do my uploading with Git.
Your directory should now look like:
(blog)stefan@aether:~/proj/blog$ ls content develop_server.sh Makefile output pelicanconf.py publishconf.py
You can now also edit
pelicanconf.py by hand to make some final adjustments. Take a look at the Pelican Documentation - Settings chapter. This is how I made mine look:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
#!/usr/bin/env python # -*- coding: utf-8 -*- # AUTHOR = u'stejoo' SITENAME = u'sjoosten.nl' SITEURL = 'http://www.sjoosten.nl' TIMEZONE = 'Europe/Amsterdam' DEFAULT_LANG = u'en' DEFAULT_DATE_FORMAT = ('%Y-%m-%d(%a)') DEFAULT_PAGINATION = 10 TYPOGRIFY = 'True' #THEME = '' # Blogroll LINKS = (('AT Computing', 'http://www.atcomputing.nl/'), ('Tweakers', 'http://tweakers.net'), ('FreeBSD', 'http://www.freebsd.org'), ('Debian', 'http://www.debian.org'), ('OpenWRT', 'https://openwrt.org'),) # Social widget SOCIAL = (('twitter', 'http://twitter.com/stejoo'),)
It’s possible to add more things like paths/files to include (
favicon.ico come to mind), Google Analytics identifier, a Disqus identity so people can react to your blog posts using it, etc…
I’m starting off with this one, and I’ll add or change things later on.
Another thing you could do is install themes or start designing your own. Pelican provides a utility to help you with installing themes, it’s called
pelican-themes. Read up on it if you are interested in changing the look of your blog using existing themes.
If you feel confident enough to create your own theme, take a look at How to create themes for Pelican.
Ready to make your first blog post?
Place your posts in the
content directory, this is the directory Pelican uses as a source to build the HTML files. So let’s change to it now and start a new file:
(blog)stefan@aether:~/proj/blog$ cd content/ (blog)stefan@aether:~/proj/blog/content$ vi hello-world.md
vi with the editor of your choice.
This is what I put in as a first post in Markdown:
Title:Hello world Date: 2013-03-07 Tags: awesome Category: Blog Slug: hello-world Author: stejoo My first blog post.
Save your file and let’s ask Pelican to process it.
(blog)stefan@aether:~/proj/blog$ pelican -s ~/proj/blog/pelicanconf.py ~/proj/blog/content/
If it returns any errors, you will have to try and hunt them down. Make sure you used the right paths and the syntax of your configuration file and post are correct. Often Pelican will tell you whats wrong. Warnings can be ignored, but fixing them too is always better.
View the results
You could point your browser at your output directory:
$ firefox ~/proj/blog/output/index.html
Or you can run Pelican’s little web server, which is intended for the purpose of testing your blog before you copy your newest posts to your web server. It will serve the contents of the
output directory at http://localhost:8000. And in the meantime it will watch the
content directory for changes, so any change you make there will show up.
(blog)stefan@aether:~/proj/blog$ ./develop_server.sh start
Once you are done viewing your blog, stop the develop_server using:
(blog)stefan@aether:~/proj/blog$ ./develop_server.sh stop
Ready for deployment
You can now upload the contents of the
output directory (or the entire project) to a machine running a web server and publish your blog on the internet that way. Because it’s just HTML, pretty much any web server will do. You could even use your Raspberry Pi for this.
Stay tuned for some more blog posts about hosting this on your own server.