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.
-
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. -
Change the output directory to parent folder. In default setting file
pelicanconf.py
, add:OUTPUT_PATH = '../'
-
Generate files.
Skipped.
-
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
- 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
-
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 contentNote: this method could only link to webpages (i.e. markdown documents). To link to other files, see:Pelican Doc:Linking to static files