Fork me on GitHub

Using Pelican and Github to Blog - Start

1. Install Pelican

Note : Before reading this article, a quick scan over Jykell Install would be very helpful in building a basic knowledge.

1.1 What, "Static Website" ?

See: Wikipedia: Static Website

1.2 Which static website generator?

A great website: Static Site Generators - The definitive listing of Static Site Generators

I choose: Pelican, because it's the best one written in python. Getting those written in Ruby run on windows could be a nightmare.

1.3 Install

See: Installation pip and Quick Start for Pelican.

1.3.1 with easy_install

I Tried install pelican through pip but failed. pip reports Failure every time I tried.

Update: Now pip is bundled in default with python installer on Windows (2016/05/27). Se the next section for installing with pip.

So I switched to easy_install

See Link 1 to install easy_install. Then find easy_install inside python installation directory (usually under folder "Scripts"),

Some WARNINGs:

==========================================================================
WARNING: The C extension could not be compiled, speedups are not enabled.
Failure information, if any, is above.
Retrying the build without the C extension now.

==========================================================================
WARNING: The C extension could not be compiled, speedups are not enabled.
Plain-Python installation succeeded.
==========================================================================
Adding MarkupSafe 0.18 to easy-install.pth file

It seemed everything work fine. So I ignored above warnings.

Then I install Markdown package to support markdown syntax

easy_install Markdown

There seemed to be a problem on my Windows 8. Easy_install downloaded the installed but failed to run it. So I run it manually. (Discovered the downloaded folder inside the errors reported by easy_install)

1.3.2 with pip

Simply run the command:

pip install pelican markdown

Wow, pip is really simple to use. It works just like apt-get install in Ubuntu, despite that the version bundled with python install is so old that the pip suggests me to upgrade it. For simplicity, I ignore this suggestion.

2. Configure

2.1 Learn Markdown (or something else)

Pelican supports many simply-markup language including markdown and reStructured Text etc. I chose markdown because I have previous experience with them. See my markdown show case. Choose whatever you like by Google it.

Important: Store your files in UTF-8 encoding, otherwise there might be problem for pelican to generate the output. If you don't know what encoding means, then you are not the intended reader for this article. Please turn to other popular blogging website.

2.2 Learn Pelican

2.2.1 Kick Start

See: Basic Usage and Kickstart Your Site

You can create a skeleton project via the pelican-quickstart command, which begins by asking some questions about your site: 

pelican-quickstart

Then view the output page: 

firefox(or something else) output\index.html

However, because the above method may have trouble locating your CSS and other linked assets, running a simple web server using Python will often provide a more reliable previewing experience: 

cd output && python -m SimpleHTTPServer

Note : In python 3, modulus SimpleHTTPServer has been replaced by http.server.

2.2.2 Push to Github Pages

  • Change the output directory:

Because the I want to use git to control my blogs, I setup something.

  1. Put the files to be read by pelican into a sub folder where html files are generated. Now, website generated by Pelican reside in the parent folder and the content read by Pelican is in a sub folder. This seperates the websites and files to be read by Pelican and in the mean time allow both Github Page to read file index.html as well as Pelican to read its files without interface each other.

  2. Change the output directory to parent folder. In default setting file pelicanconf.py, add:

    OUTPUT_PATH = '../'

  3. Generate files.

    Skipped.

  4. Push to Github

    Follow guide Here to create a "User or organization site".

    Then clone the the source, copy your prepared Pelican generated websites (including where you store the files read by Pelican) to the cloned folder. Commit and Push and Done with your first blog!

2.2.3 Using other's themes.

Some websites built on Pelican:Powered by Pelican

Some good themes:
Site:http://omphalosskeptic.github.io
Source: https://github.com/omphalosskeptic/omphalosskeptic.github.io

Site: http://kylefuller.co.uk/
Source: https://github.com/kylef/kylefuller.co.uk

More

Detailed settings of Pelican can be seen here:Pelican Settings

Resources

  • Recommend Pelican Official Doc
  • Recommend Some cases you can learn from [Powered by Pelican] (https://github.com/getpelican/pelican/wiki/Powered-by-Pelican)

Problem Solver:

  • In Pelican: 'utf-8' codec can't decode byte 0xbe in position 2458: invalid start byte
    Why: Some files are stored in encoding GBK (or something else other than UTF-8) which is not supported by Pelican by default. Since python (and almost everything else) suppports utf-8, use some text editor (mine is notepad++) to change encoding to utf-8. [SOLVED]

Tips

  1. Pelican does not provide a overall view of tags or categories already exist. However, you can find all the tags and categories in the output folder easily. To Be Continued

  2. Link to local webpages etc:

    [a link relative to the current file]({filename}category/article1.rst)
[a link relative to the content root]({filename}/category/article1.rst)

    Notice that the root directory is taken to be the content directory. See more at:Pelican Doc: Linking to internal content

    Note: this method could only link to webpages (i.e. markdown documents). To link to other files, see:Pelican Doc:Linking to static files

blogroll

social