# How to use [Pelican](http://docs.getpelican.com) on [GitHub Pages](http://pages.github.com) [![Gittip](https://raw.github.com/gittip/www.gittip.com/master/img-src/gittip-logo-32.png)](https://www.gittip.com/josefjezek)

Author: [Josef Jezek](http://about.me/josefjezek)

## Install on Ubuntu

### Installing Python tools

```
sudo apt-get install python-setuptools
sudo easy_install pip
sudo pip install virtualenv virtualenvwrapper
```

`vi ~/.bashrc` (maybe `virtualenvwrapper.sh` is in other location, change if necessary)

```sh
# Virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh
```

Load file `.bashrc`

```
source ~/.bashrc
```

Create [virtualenv](http://www.virtualenv.org/en/latest/) with [virtualenvwrapper](http://www.doughellmann.com/projects/virtualenvwrapper/)

```
mkvirtualenv blog
workon blog
```

And to leave

```
deactivate
```

### Installing Pelican

```
sudo pip install pelican markdown ghp-import shovel
```

### Upgrading Pelican

```
sudo pip install --upgrade pelican markdown ghp-import shovel
```

## Creating a blog on [GitHub Pages](https://help.github.com/categories/20/articles/)

We need to make a respository. For example blog, so our blog url will be `user.github.com/blog`. If you want to set a custom domain see link: [Setting up a custom domain with Pages](https://help.github.com/articles/setting-up-a-custom-domain-with-pages)

### Steps to publish a post

In parenthesis is the git branch we are working on:

1. (`master`) Create the post in rst or md (rst and md are abbreviations for resTructuredText and markdown)
2. (`master`) Generate the HTML
3. (`master`) Check the post in a local server
4. (`master`) We could delete the output but dones't matter if we don't because git will ignore with our gitignore file
5. (`gh-pages`) Merge master branch
6. (`gh-pages`) Generate the HTML
7. (`gh-pages`) push all the files (normally all the new HTML)
8. (`master`) push all the files (normally only one post)

### Clone git repository

```
git clone git@github.com:user/blog.git
cd blog
```

Create in the root folder a file `.gitignore`

`vi .gitignore`

```
#Custom
output

#Python
*.py[cod]

# C extensions
*.so

# Packages
*.egg
*.egg-info
dist
build
eggs
parts
bin
var
sdist
develop-eggs
.installed.cfg
lib
lib64

# Installer logs
pip-log.txt

# Unit test / coverage reports
.coverage
.tox
nosetests.xml

# Translations
*.mo

# Mr Developer
.mr.developer.cfg
.project
.pydevproject
```

### Download Themes

Clone `pelican-themes` repository

```
git clone --recursive https://github.com/getpelican/pelican-themes themes
```

### Create Pelican settings file

Create settings file called `settings.py` from sample `pelican.conf.py`

```
wget -O settings.py https://raw.github.com/getpelican/pelican/master/samples/pelican.conf.py
```

Add this variables 

```
THEME = 'themes/bootstrap2'
OUTPUT_PATH = 'output'
PATH = 'src'
```

Period archives work best when the final path segment is `index.html`, see [URL Settings](http://docs.getpelican.com/en/latest/settings.html#url-settings)

```
ARTICLE_URL = 'posts/{date:%Y}/{date:%m}/{slug}/'
ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%m}/{slug}/index.html'
```

### Custom Home page

Add this variables to `settings.py`

```
# Custom Home page
DIRECT_TEMPLATES = (('index', 'blog', 'tags', 'categories', 'archives'))
PAGINATED_DIRECT_TEMPLATES = (('blog',))
TEMPLATE_PAGES = {'home.html': 'index.html',}
```

Duplicated the `index.html` to `blog.html` in your template folder and add this lines:

```
{% set active_page = "blog" %}
{% block title %}{{ SITENAME }} - Blog{% endblock %}
```

Create `home.html` or use [page override](http://docs.getpelican.com/en/latest/faq.html#how-can-i-use-a-static-page-as-my-home-page) feature to use a Markdown page as your home page.

`vi home.html`

```
{% extends "base.html" %}
{% block content %}
<div class='page'>
  <div class="page-header"><h1>Home</h1></div>
  <div class="page-content">Content</div>
</div>
{% endblock %}
```

### Creating post

```
mkdir -p src/posts/2013/07
vi src/posts/2013/07/welcome-all.md
```

```
Title: Welcome All
Slug: welcome-all
Date: 2013-07-22 19:19
Category: Python
Tags: pelican, publishing
Author: Josef Jezek
Summary: Short version for index and feeds

This is the content of my blog post.
```

### Generate blog

To generate the static html we use:

```
pelican -s settings.py
```

This will take all the settings and apply, but if we want to override some settings we could do. For example to specify the ouput we use `-o`:

```
pelican -s settings.py -o /tmp/blog
```

Issues

* `WARNING: LOCALE option doesn't contain a correct value` see [Ubuntu Locale](https://help.ubuntu.com/community/Locale)

Then we have a new directory named `output`, our blog is there, so, to test it , insert there and run a simple server:

```
cd output
python -m SimpleHTTPServer 8000
# For Python 3
python -m http.server 8000
```

Point your browser to `localhost:8000` and you will see the blog.

### Deploying the blog

We start the process in the `master` branch:

```
git add .
git commit -m "First post: Welcome All"
```

Push it to master (remember, this doesn't deploy the page, this is our source):

```
git push origin master
```

If we havent the gh-pages branch we create:

```
git branch gh-pages
```

Change to gh-pages and merge the master branch:

```
git checkout gh-pages
git merge master
```

Now generate the HTML. But wait! github doesn't know that our webpage is in output dir, so we need to put our generated HTML in the root of the project, to do that we replace the settings outputdir in the command:

```
pelican -s local_settings.py -o ./
```

We are ready to deploy, commit all and push:

```
git add .
git commit -m "Publish Welcome All post"
git push origin gh-pages
```

We change again to our master branch and we are done :):

```
git checkout master
```

Point your browser to you.github.com/blog , Awesome!!!



## Resources

* http://blog.xlarrakoetxea.org/posts/2012/10/creating-a-blog-with-pelican
* http://docs.getpelican.com/en/latest/getting_started.html
* http://docs.getpelican.com/en/latest/tips.html#publishing-to-github
* http://raichev.net/blohg-to-pelican.html
* https://github.com/getpelican/pelican/issues/735#issuecomment-17674540