How-to: Make a Site with Pelican | Computational Approaches to Biological Problems

I've tried generating static sites on my own before. I've even tried it with pelican and jekyll. And even given all of the great documentation to get started, it still felt a bit overwhelming. So, after yet another attempt to get something that looked like a manageable, visually appealing site, it seems I might actually have something worth showing.

So, here, I will describe how I did it in the off chance that it may be helpful to someone else also.

To get started, I went straight to the Pelican quickstart tab. Then, I opened the terminal to install pelican. Now, normally one should follow the installation guide on the documentation page. However, as I do all of my python work through my local Anaconda distribution, I had to figure out how to get it installed on my Ubuntu virtual machine.

Short answer:

conda install -c conda-forge pelican markdown

Next, I actually followed the quickstart directions

mkdir jlboat.github.io   # name of my soon-to-be static site directory
cd jlboat.github.io

pelican-quickstart

Conveniently, pelican gets you started by asking simple questions so it can auto-generate the basics of your site.

pelican-quickstart
Welcome to pelican-quickstart v3.7.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.


> Where do you want to create your new web site? [.] 
> What will be the title of this web site? Computational approaches to biological problems
> Who will be the author of this web site? J. Lucas Boatwright
> 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) 
> What is your URL prefix? (see above example; no trailing slash) https://github.com/jlboat 
> Do you want to enable article pagination? (Y/n) 
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Paris] EST
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (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) 
> Do you want to upload your website using S3? (y/N) 
> Do you want to upload your website using Rackspace Cloud Files? (y/N)
> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at /home/lucas/Documents/Projects/Personal/jlboat.github.io

Once you get the basic setup ready for your pelican site, you're going to want to add a theme (unless you're okay with an ugly HTML page without any CSS to make it pretty).

To do that, either download or clone the pelican-themes repository and install a theme you like (you may find a gallery here or some of the themes have PNG examples in their directories)

git clone --recursive https://github.com/getpelican/pelican-themes ~/pelican-themes
pelican-themes --install /home/lucas/pelican-themes/nest

Now, you need to add the theme you like to the pelicanconf.py as well.

vim pelicanconf.py  # or your editor of choice

## INSIDE THE EDITOR
#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals

AUTHOR = 'J. Lucas Boatwright'
SITENAME = 'Computational approaches to biological problems'
SITEURL = ''
THEME = '/home/lucas/pelican-themes/nest'                 # <-- Edit here

For examining the state of the static site locally (before pushing to GitHub), I had to uncomment the last line in the pelicanconf.py file.

# Uncomment following line if you want document-relative URLs when developing
RELATIVE_URLS = True                                      # <-- Edit here

Then, it's as simple as:

make html

This should be enough to get you started. I further recommend going to the theme's GitHub site (for example: nest) to see what the default configuration settings are, and how you may further customize your theme.