After completed several data science projects, I am eager to document them and share them with people. It took me several days to research, set up and write my blog, but I feel it can be much easier and faster to build a Pelican blog, so I am sharing with you the lessons I have learned in building my first data science blog, the code is available here.
Table of Contents
- Find a Static Site Generator
- Basic Setup
- Install Pelican Theme
- Write Content
- Publish Your Site
- More Setups
Find a Static Site Generator
There are lots of discussions on the Internet about pros and cons between static site and dynamic site static_vs_dynamic. For me, I am build a small size personal website, static site will fully meet my needs, and it is faster to load, and it allows me to write blog posts in simple format, such as markdown file. So if you are write a small/medium personal site, go with static! There are several static site generators to choose from, such as jekyll, nikola, etc. Recently, Pelicanis has gain lots of popularity among the data science community, and I saw many people are moving their blogs to Pelican, so I choose to use Pelican, it has lots of online resources and user community support, and it is built in my favorite Python language.
Basic Setup
Read official Pelican documentation first, most of the questions can be found there.
Install and Activate Virtual Environment
A virtual environment is an isolated Python environment in which we store our Pelican blog site. We build an isolated environment so that if we make changes or update a Python package or Python version outside the virtual environment, it does not affect the Python used in our Pelican site. Steps are as follows: - open your Linux terminal(I use git bash), install virtualenv, and activate virtualenv, after activation, you will see your Linux command start with(pelican)
pip install virtualenv
virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs
source ~/virtualenvs/pelican/Scripts/activate
Install Pelican Under Virtual Environment
Next, we install Pelican under virtualenv, make sure (pelican) is shown at the beginning of your Linux command. The last four commands are optional, use them if you want to install Markdown, typogrify, update pelican, or read help file.
pip install pelican
pip install Markdown
pip install typogrify
pip install –upgrade pelican
pelican –help
Quickstart Your Site
Quickstart your site, select your choices. After the following command, you will see the output of your project location, write down the location, you will use it later.
pelican-quickstart
Install Pelican Theme
Pelican comes with its default theme, but you can change your themes really easy from Pelican-themes github repo. Before selecting the theme you want to install, take a look at the preview of various Pelican themes. I use the very popular bootstrap3 theme, which comes with many functions. I choose bootstrap3 theme particularly because it support IPython Notebook, it includes many more themes based on bootstrap3 which you can choose from bootswatch. Moreover, you can include a profile picture and a simple description of yourself.
First, download or clone from the github repo containing the theme you want to use, next, install it to your Pelican blog by the following commmand The last two commands are optional which list themes installed. write down the location where it is stored.
pelican-themes --install ~/virtualenvs/pelican-themes/boostrap3 --verbose
pelican-themes –l # list themes installed
pelican-themes –v –l # list themes installed with path
For a boostrap3 theme to work, you also need to install pelican-plugins from this github repo. Clone or copy the pelican-plugin folder, add the following lines to pelicanconf.py located in ~/virtualenv/pelican folder.
THEME = 'path/to/bootstrap3/stored/pelican-bootstrap3'
JINJA_ENVIRONMENT = {'extensions': ['jinja2.ext.i18n']}
PLUGIN_PATHS = ['/path/to/git/pelican-plugins']
PLUGINS = ['i18n_subsites']
To select a theme from bootswatch: http://bootswatch.com/, all you need to do is add the following line to your pelicanconf.py BOOTSTRAP_THEME = 'bootswatch_theme'
Write Content
Create three folders in your content folder, name them images, pages and posts, respectively. images folder stores all the images you want to use in your blog. Next, create a markdown file (about.md) and store in pages folder, where about_me is stored. In the end, create several markdown files in posts folder where each file contains the content of a post.
Include the following metadata in each of your markdown files.
Title: How I Build My First Pelican Blog
Date: 2017-06-14 16:00
Modified: 2017-06-15 16:00
Category: Tutorials
Tags: Python, Pelican
Slug: my-super-post
Authors: Yanting Cao
Summary: A tutorial of my first pelican blog
Write my content here ...
If you are not familar with markdown syntax, here is a link to a Markdown cheatsheet.
Publish Your Site
We have gone this far, let's now take a look at our blog.
pelican ~/virtualenvs/pelican/content/ -s ~/virtualenvs/pelican/pelicanconf.py
cd output
python –m http.server
Once the basic server has been started, you can view your site at http://localhost:8000/
More setups
If you want to make your blog look better, I will teach you more setups, including side bar and banner (this specifically applies to bootstrap3 theme, if you use a different theme, refer to the descriptions in the theme's github repo)
Side Bar
Side bar has options including display an image, Social(github, linkedin, twitter, facebook, etc.), Categories, Tags and Links.
Display an image on the side bar Save image in png file under 'content/images', add the following lines in your pelicanconf.py
PATH = 'content'
STATIC_PATHS = ['images']
AVATAR = 'images/side_bar_pic.png'
Show Social Links Include the following lines in your pelicanconf.py
SOCIAL = (('twitter', 'http://twitter.com/youraccount', 'twitter'),
('linkedin', 'http://www.linkedin.com/in/youraccount', 'linkedin'),
('github', 'http://github.com/youraccount', 'github'),
('stackoverflow', 'http://stackoverflow.com/users/youraccount', 'stack-overflow')
Show Tags Also in your pelicanconf.py, add the following codeconquest
DISPLAY_TAGS_ON_SIDEBAR = True
PLUGINS = ['tag_cloud']
Show Categories Add the following line to pelicanconf.py
DISPLAY_CATEGORIES_ON_SIDEBAR = True
Show Links Add the following line to pelicanconf.py
LINKS = (('Kaggle','kaggle.com'),
('Rady School of Management, UCSD', 'http://rady.ucsd.edu/'),
('Python.org', 'http://python.org/'),
('Pelican', 'http://getpelican.com/'))
Banner
Adding a banner image and subtitle to your blog by the following code
BANNER = '/path/to/banner.png'
BANNER_SUBTITLE = 'This is my subtitle'
Now, we have built our first Pelican blog. Many thanks to Pelican, the free static site generator, as well as to Daan Debie, author of bootstrap3. Let's now start writing in our blogs !