# How to Pelican

## Install on Ubuntu

Installing Python tools

```
sudo easy_install pip
sudo pip install virtualenv
sudo pip install virtualenvwrapper

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

source ~/.bashrc
mkvirtualenv blog
workon blog

# And to leave:
deactivate
```

Installing Pelican

```
sudo pip install pelican
sudo pip install markdown
```

Upgrading

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

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

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

### Create git repository

Clone git repository

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

Create in the root folder a file named `.gitignore`

`vi .gitignore`

```
#Custom
local_settings.py
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
```

### Create a Pelican settings file

Now we will create a pelican settings file called `local_settings.py`, this file will not be commited to the git repo, maybe has personal data. But we will upload a blank template named `settings.py`, so we create also this one, that has the same variables as `local_settings.py` but without the vars data. Edit the data you need (You can store the `local_settings.py` data in a private gist manually):

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

To generate the static html we use:

```
pelican -s ./local_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 ./local_settings.py -o /tmp/myBlog
```

### Creating a post

```
mkdir -p ./posts/2013/07
vi 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

# Welcome All

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

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