Pelican

Starting with Pelican

Begin by using pip to install pelican and markdown:

pip install pelican markdown

or install via Pelican Github repo:

• https://github.com/getpelican/pelican

Pelican documentation is here:

• http://docs.getpelican.com/en/3.5.0/

and the Pelican quickstart guide is here:

• http://pelican.readthedocs.org/en/3.5.0/quickstart.html

Using Pelican with Github Project Page

If you want to use pelican to manage a github project page, start by creating a "source code" bundle for your Pelican site in the master branch. This will deploy static content to the gh-pages branch, which is what shows up when you visit http://username.githubpages.io/project-name.

Starting Your Pelican Site

Start in the master branch of your project. Here, I'll use my Words, Words, Words project as an example.

$ pwd
/Users/charles/codes/wordswordswords/pelican

Now I create the site with the pelican-quickstart command, answering some questions from Pelican:

$ pelican-quickstart

Welcome to pelican-quickstart v3.5.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

> Where do you want to create your new web site? [.] > What will be the title of this web site? Words, Words, Words
> Who will be the author of this web site? CR
> What will be the default language of this web site? [en]
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10]
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) y
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) y
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) n
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) n
> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) n
Done. Your new project is available at /Users/charles/codes/wordswordswords/pelican

Creating Markdown Content for Pelican Site

Once your Pelican site has been created, we can create markdown content by putting markdown files into the content/ directory. For example,

Title: An Article
Date: 2014-12-21 10:20
Category: Essay

This is just an ordinary article.

We can then generate static content from the markdown files by running the pelican content command:

$ pelican content
Done: Processed 1 article(s), 0 draft(s) and 0 page(s) in 0.33 seconds.

and preview the site by going into the output/ directory and running a simple HTTP server with Python:

$ cd output/

$ python -m SimpleHTTPServer
Serving HTTP on 0.0.0.0 port 8000 ...

Then you can visit http://localhost:8000 to see the site preview locally.

The next steps involve connecting this output folder to the Github branch that is pointed to by our Github Project page's live hosted static content. That way, we can type pelican content to generate content, and then use git push to push the freshly-generated content to the live Github Pages project site.