Simple steps to a personal blog
This personal blog is constructed on the following components:
Some more details could be found in the homepage of the aforementioned projects. The following parts provides an initial setup for static personal webpages.
Why Pelican ?
Well, there are certainly many other excellent choices like Jekyll. While for someone with a heavy reliance on Python, Pelican constitutes a better tool.
Software Setup
Before starting, one needs to install Pelican, Markdown and one Markdown Editor. One easiest way to install is using the "pip" command:
pip install pelican
pip install Markdown
There are some other tools that are optional but quite useful, such as Pandoc, which provide powerful support for a wide range of markup format. Another usefull tool could be IPython.
As to the Markdown editor, for MAC users, the best choice is Mou; and for Windows uders, MarkdownPad is perhaps the most siutable one.
After installation, some configurations are needed to make the writing more confortable, including installing some useful plugins and choosing a suitable theme. Those steps will be shown below.
Simple Steps
To start, make one working directory for the blog, and generate the fundamental structures with Pelican Quick Start:
mkdir blog
cd blog
pelican-quickstart
Now a series of files and folders are generated. Download the Pelican Theme from the official repository and put the decompressed folder in the working directory (here, the "/blog" directory). Check the avilable themes through:
pelican-theme --list
Choose one theme in the list (like "bootstrap"), run:
pelican-theme --install ~/path/to/pelican-themes/bootstrap --verbose
Now download the offical plugins and decompress into the working directory. In this blog, we rely on a plugin called liquid_tags. Open the configuration file pelicanconf.py and add the following lines:
import os
# Choose a theme
THEME = 'bootstrap'
# Specify the directory of the plugins and which plugin is to be used
PLUGIN_PATH = 'pelican-plugins'
PLUGINS = ['liquid_tags.img', 'liquid_tags.video',
'liquid_tags.include_code', 'liquid_tags.notebook',
'liquid_tags.literal']
# Accommodate IPython notebook
if not os.path.exists('_nb_header.html'):
import warnings
warnings.warn("_nb_header.html not found. "
"Rerun make html to finalize build.")
else:
EXTRA_HEADER = open('_nb_header.html').read().decode('utf-8')
# Specify the directory of the addtional files relative to the "content" directory
NOTEBOOK_DIR = 'notebooks'
CODE_DIR = 'code'
In many cases, the chosen theme is not perfect enough and required to be modified. Here in order to work with IPython notebook, we need to some changes in the base.html file. The following code are added within the header tag:
{% if EXTRA_HEADER %}
{{ EXTRA_HEADER }}
{% endif %}
Clearly, the above code is used to integrate the _nb_header.html (generated by IPython notebook) into the theme. More details could be found at Jake Vanderplas's blog .
Now set up a repository on Github with the name username.github.io . Clone this repository in the "output" directory:
cd output
git clone https://github.com/username/username.github.io.git
Write your articles in the "content" directory with the Markdown editor. Go back to the main working directory and prepare to publish them:
pelican -s pelicanconf.py ./content -o ./output/username.github.io
The final steps would be add/commit/push all files to Github:
cd output/username.github.io
git status
git add --all
git commit -am "Your Commit Message"
git push https://github.com/username/username.github.io.git
The last step could be changed if Git has been configured properly:
git push origin master
Open https://username.github.io in your browser, and your personal blog will be shown.