Getting Started with Pelican

I'm revisiting my blogging/documentation needs again. Some of my core desires are to have the whole thing neatly version controlled where I can come back to it in 6 months and publish an article without having to remember how it was all setup to begin with. I think it's best to start at the beginning.

My primary computer is a 2017 Mac Pro without the touchbar. Yeah, I know... I probably should have dealt with the touchbar for the extra Thunderbolt ports. Well, we're not covering that here.

As usual, make sure you have Homebrew installed before beginning. It makes life good. Once you're good to go there, let's get the initial environment setup.

Track the project in source control

Let's start by tracking this in source control. I'm going to use gitlab later on for continously publishing my blog but feel free to use what works for you. At a minimum you'll want to do the following.

1
2
3
4
5
mkdir ~/pelican-blog && cd !$
touch README.md
git init
git add *
git commit -am "Initial commit"

TODO: setup the .gitignore

Setting up the python environment

Pipenv is a pretty great tool. Instead of initializing the virtualenv, activating it, and managing requirements.txt, it handles all of that for you in a simple command. Coloring outside the lines can get a little wonky but for the most part it makes virtual environments nice.

1
2
brew install pipenv
pipenv install pelican markdown beautifulsoup4

You'll notice that it drops a Pipfile and Pipfile.lock file in the current directory. This file tracks dependencies and helps set the environment back up when we copy all this code somewhere else.

If you have another way you prefer to manage python virtual environments, go for it. You'll want to be on Python 3.7 for this guide.

Getting started with Pelican

Now that you have Pelican installed, you can leverage the quickstart setup. This is one of the odd parts of working with pipenv I mentioned. To activate the environment use pipenv shell. This will drop you off at a command prompt to do work within the virtual environment.

1
2
3
pipenv shell
pelican-quickstart
# answer the questions

Now at this point, Pelican won't do much until you create at least one page.

1
2
3
4
5
6
7
8
cat > content/pelican-is-cool.md <<EOF
Title: Pelican is cool
Date: 2018-08-30
Category: Test

Hello from Pelican!
---
EOF

Time to render the site and start a test server to see if it works...

1
2
3
4
5
# Start the testing server
make devserver
# Browse to http://localhost:8000
# Stop the testing server
make stopserver

If you see your new page then CONGRATS! It worked!

Next we'll take a look at using a theme other than the default!