It just wouldn't be done to move to a new blogging platform without describing how it went, and what I did to get it working.
Most of the steps I have taken here have been shamelessly copied from the following sources, albeit with some slight modification.
- Renata's blog (This was an amazing resource. Thanks to the author for such a comprehensive setup description)
- Github - Pelican tips
This blog was set up on a 13" 2016 Macbook Pro with that awful keyboard. I use Homebrew for all the stuff that helps make the Apple's BSD environment a bit more useful, including updating my Python installation to v3. My editor of choice is Sublime Text, and I use Dropbox as a way of preserving my virtual environments. (More on that later)
The first thing to do is to create a new repository in GitHub to hold your site. The repository needs to be named: username.github.io, where username is your GitHub username, or it won't work.
Now that you have set up the repository, you'll need to prepare your local environment. I keep the site in Dropbox as additional backup/version control, but you can put it wherever you like. Clone the repository into your local environment.
$ cd path/to/where/you/want/virtualenv/to/live $ git clone https://github.com/<USERNAME>/<USERNAME>.github.io.git $ cd <USERNAME>.github.io/
Now that you're in the correct directory, you'll need to check the source out locally. Github prefers to serve the site from the master branch, so create a new branch, called source, (thanks, Renata, via Adrien Leger. Seriously, NOBODY else mentions this, and it tripped me up.).
$ git checkout -b source
Create and activate a new virtual environment inside the
$ virtualenv venv $ source venv/bin/activate
Your prompt should look similar to the following. (Note the addition of the name of the virtual environment in brackets before your prompt)
Now that you're in your virtual environment, it's time to install the relevant python packages needed for Pelican. I use Markdown to write my posts, and so need to install the markdown plugin as well.
$ pip install pelican markdown ghp-import
Once all the relevant packages are installed, it's useful to freeze so you can bring them back if necessary.
$ pip freeze > requirements.txt
Once you've done all that, you can instantiate the site using the pelican-quickstart command, which asks you some questions and sets things up accordingly. We'll be using GitHub Pages here, and you'll also need to take care of the following questions:
- What is your time zone? Mine is Europe/London, but you can find the list of values on Wikipedia. The format must be exactly as listed.
- Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Answer: Y.
- Do you want to upload your website using GitHub Pages? Answer: Y.
- Is this your personal page (username.github.io)? Answer: Y.
So, being mindful of the required answers to the questions above, you can now set up Pelican using the quickstart command.
Create a first post
Now that everything is installed, it's time to create a first post. Fire up your editor of choice, and create a new file called firstpost.markdown in the content folder under the USERNAME.github.io folder.
Your folder structure should now look similar to the following:
username.github.io |--content | |___firstpost.markdown |___venv | |___... |___requirements.txt |___...
Each post (markdown file) needs to be described by metadata, which provides some useful information for segmenting on category, date etc. The format is as below.
Title: My super title Date: 2010-12-03 10:20 Modified: 2010-12-05 19:30 Category: Python Tags: pelican, publishing Slug: my-super-post Authors: Alexis Metaireau, Conan Doyle Summary: Short version for index and feeds This is the content of my super blog post.
<snippet> <content> Title: $1 Date: $2 Modified: $2 Category: $3 Tags: $4, $3 Slug: $5 Authors: Pierre Summary: $6 $7 </content> <!-- Optional: Set a tabTrigger to define how to trigger the snippet --> <tabTrigger>blogpost</tabTrigger> <!-- Optional: Set a scope to limit where the snippet will trigger --> <scope>text.html.markdown, text.html.markdown.multimarkdown</scope> </snippet>
Once you've saved your new file, you can test it locally by running the following:
(venv) $ make html && make serve
This will create a local web server on your machine, which you can test by browsing to localhost:8000.
If you're looking at your post, well done. It's working as expected.
This won't look the same as yours by default, as I've already changed my theme. (We'll get to that later)
In Part 2, I'll talk about config options, cloudflare setup and pushing content to live., (while testing locally).