# 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 fabric
```

`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
```

### Upgrading Pelican

```
sudo pip install --upgrade pelican markdown
```

## 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!!!

### Automation

[Fabric](http://fabfile.org) is a tool, an awesome tool! to automate things, is most used for remote servers, but also works fine for local automation. Put `fabfile.py` in the root path of the blog in the `master branch`.

Now you can use like this:

* `fab generate`: generates the html for developing (while writing)
* `fab serve`: Serves the blog in local
* `fab publish`: Does all the process of change, commit and publish gh-pages branch, needs to be in `master branch` while executing the command

`vi fabfile.py`

```python
import os
import time

from fabric.api import local, lcd, settings
from fabric.utils import puts
from settings import OUTPUT_PATH

SETTINGS_FILE = "settings.py"

# Get directories
ABS_ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
ABS_SETTINGS_FILE = os.path.join(ABS_ROOT_DIR, SETTINGS_FILE)
ABS_OUTPUT_PATH = os.path.join(ABS_ROOT_DIR, OUTPUT_PATH)


# Commands
def generate(output=None):
    """Generates the pelican static site"""

    if not output:
        cmd = "pelican -s {0}".format(ABS_SETTINGS_FILE)
    else:
        cmd = "pelican -s {0} -o {1}".format(ABS_SETTINGS_FILE, output)

    local(cmd)


def destroy(output=None):
    """Destroys the pelican static site"""

    if not output:
        cmd = "rm -r {0}".format(os.path.join(ABS_ROOT_DIR, OUTPUT_PATH))
    else:
        cmd = "rm -r {0}".format(output)

    with settings(warn_only=True):
        result = local(cmd)
    if result.failed:
        puts("Already deleted")


def serve():
    """Serves the site in the development webserver"""
    print(ABS_OUTPUT_PATH)
    with lcd(ABS_OUTPUT_PATH):
        local("python -m SimpleHTTPServer")


def git_change_branch(branch):
    """Changes from one branch to other in a git repo"""
    local("git checkout {0}".format(branch))


def git_merge_branch(branch):
    """Merges a branch in other branch"""
    local("git merge {0}".format(branch))


def git_push(remote, branch):
    """Pushes the git changes to git remote repo"""
    local("git push {0} {1}".format(remote, branch))


def git_commit_all(msg):
    """Commits all the changes"""
    local("git add .")
    local("git commit -m \"{0}\"".format(msg))


def publish():
    """Generates and publish the new site in github pages"""
    master_branch = "master"
    publish_branch = "gh-pages"
    remote = "origin"

    # Push original changes to master
    #push(remote, master_branch)

    # Change to gh-pages branch
    git_change_branch(publish_branch)

    # Merge master into gh-pages
    git_merge_branch(master_branch)

    # Generate the html
    generate(ABS_ROOT_DIR)

    # Commit changes
    now = time.strftime("%d %b %Y %H:%M:%S", time.localtime())
    git_commit_all("Publication {0}".format(now))

    # Push to gh-pages branch
    git_push(remote, publish_branch)

    # go to master
    git_change_branch(master_branch)
```

## 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