Using this repo

The workflow for how to maintain my blog and also keep up to date with the latest pelican releases was not immediately apprent to me. This README provides some notes on the workflow and also instructions on how to recreate a static site using this repo along with a pelican themes repo.

Hopefully others may find the sample configuration tweaks and instructions usefull.

This repo contains the content and tweaks for my robren.net blog. To understand how to use this repo to recreate my blog, or hopefully your own but with the benefit of example configuration, we need to understand how a from-scratch i.e blank canvas pelican blog would be created.

Creating a pelican blog from scratch

The pelican static site generator is well described in the pelican documentation

A quick summary of what one would do if starting a new blog from scratch is:

• Install pelican, typically in a virtualenv and done via pip install.
  • While pelican will run using python 3, the fabric automation scripts only work with python 2.5 to 2.7. Thus ensure that python2.7 is installed in the virtualenv e.g mkvirtualenv robren-blog -p python2.7
• Run the pelican-quickstart command to create a project framework
• Tweak the confguration settings in pelicanconf.py and publishconf.py
• Create content in the content directory, e.g markdown or rst files
• Invoke the pelican command or the fab command to generate and deploy the blog.

Recreating my already configured blog

What's included in this repo is what one would get after running the pelican-quickstart command and then:

• Creating content, i.e blog entries in the content directory
• Editing the pelicanconf.py and publishconf.py to point to point to custom css and the pelican theme chosen, bootstrap3 in my case.
• The fabfile.py which would be autogenerated by pelican-quickstart

To recreate this blog, there's no need to run the pelican-quickstart.

Steps

The following steps should be performed preferably in a virtualenv.

• Install pelican

    pelican pip install pelican

• Alternatively
  • If deploying the blog in a docker container is desirable, the pip installation must be pointed at my fork. It's currently under-review as of Dec 2016

    pip install -U git+https://github.com/robren/pelican@docker-nginx-deploy

• Using this version of pelican is only required if one wants to create a blog from scratch and also get extensions to the fabfile. Installing stock pelican and cloning my blog repo and editing content in this will give the latest pelican as well as the extensions in the fabfile.

• Clone the pelican themes repo alongside the blog directory

  • Or wherever you want, just set the THEME = 'path-to-theme' in pelicanconf.py

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

• Clone the robren-blog

    git clone https://github.com/robren/robren-blog

• Install yet more dependancies
  • Pelican will give some very cryptic error mesages without these

    pip install fabric
    pip install Markdown   # My blog is written in markdown
    pip install typogrify

• Now you can run the pelican command to generate the blog, or the fab command or ... the make commands.

Ongoing workflow

• The version of pelican can be updated using

    pip install -U pelican

• The themes updated by performing a git pull in the pelican-themes directory

• The blog updated by adding new content and "publishing it" using one of the "fabric" commands

	test-lt :: ~/Blog/robren-blog » fab -l
	Available commands:

		ComplexHTTPRequestHandler
		build                      Build local version of site
		cf_upload                  Publish to Rackspace Cloud Files
		clean                      Remove generated files
		docker_rebuild             Rebuild the pelican site for production and install in a docker image :
		gh_pages                   Publish to GitHub Pages
		preview                    Build production version of site
		publish                    Publish to production via rsync
		rebuild                    `clean` then `build`
		regenerate                 Automatically regenerate site upon file modification
		reserve                    `build`, then `serve`
		serve                      Serve site at http://localhost:8000/

• So to create a docker image. from the root of the blog run the folowing command.

	test-lt :: ~/Blog/robren-blog » fab docker_rebuild

Currently this creates an image as well as runs the docker image.

TODO decouple creating the image from running it. This will allow cleaner integration with an alternative container workflow, e.g. running within Kubernetes.