I wanted to write a post on the process I went through creating this blog. It is a culmination of about 6 month's work trying different options and finally ending up with as perfect a mix of features as possible. Of course this is an ongoing project and I will be learning new things about Pelican and how I can incorporate them into the site. All in all, Pelican is an impressive framework. If used well the workflow is efficient where you can quickly create posts and incorporate them into your blog with minimum hassle.

The set of features that I finally settled for were arrived at in a round about way. In the beginning, I didn't even know I wanted these features but as I started using it and getting more and more familiar with the process and what was on offer, not having some of these features became a deal breaker. The final list is set out below. I know that other platforms implement some of these (and also quite well). But I like the way that Pelican implements them.

  1. Natively Windows
  2. Custom theme
  3. Markdown with code syntax highlighting
  4. Latex for math equations
  5. Host on Amazon S3 as a static site
  6. Comments
  7. Version control
  8. Other important points

So lets get into it.

Setup

The setup assumes you already have Python installed. Additionally development will be done on a PC. If you have multiple Python projects on your PC, it is a good idea to create each of those within a Python virtual environment. You can think of this as a container with your Python installation in it. All libraries particular to the project are installed within the container. It helps you maintain specific versions of libraries within the containers and cluttering up your main Python installation.

> virtualenv venv
> venv\scripts\activate

Once the virtual environment has been installed and activated, the required packages for blog can be installed locally.

> pip install pelican markdown pygments

A Natively Windows Setup

Once the necessary packages are installed, we are ready to begin. Pelican offers a quick way of setting up your blog with the pelican-quickstart command. I will go through the settings I have used and then give an explanation of why I used them. Default values normally appear within brackets (with the chosen option capitalized in the case of yes / no answers)

> Where do you want to create your new web site? [.]
> What will be the title of this web site? findingpatterns
> Who will be the author of this web site? Karim Lameer
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n)
> What is your URL prefix? (see above example; no trailing slash) www.findingpatterns.co.uk
> Do you want to enable article pagination? (Y/n)
> How many articles per page do you want? [10] 5
> What is your time zone? [Europe/Paris]
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) n
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n)

Explanation of quickstart settings

urlprefix - There are different settings for development and for publishing the blog. For development, you will be running a local server links will be relative to your localhost. When publishing, your links need to be relative to your website's URL. Because of this, there are two settings files to use depending on what you are doing with the blog. pelicanconf.py for development and publishconf.py for publishing. The website url for the blog will be in publishconf.py

article pagination - The number of article summaries to appear on your home page. This is a personal setting and needs to work well with the theme you decide on.

Fabfile/Makefile - For development on Linux environments. The Windows equivalents of these files will be created in this tutorial.

simpleHTTP Script - Gives you useful Python tools for development.

Create files to streamline workflow

I have an obscene number of Python projects on my PC. Each of which I attend to at different levels of regularity. Although I have the best intentions to blog all regular, sometimes I return to my blogging app after months only to realise that I have forgotten the process. To help future me, I have written batch files to do the regular tasks of the website. All I have to do is to put descriptions of all the scripts in the apps README.md file to jog my memory. This way I can rock up at any time, write a post and run the scripts and disappear.

pelrun.bat - runs in a process and compiles the website when it detects code changes.

pelican content --debug --autoreload --output output --settings pelicanconf.py

pelserve.bat - runs Pythons SimpleHTTP Server so you can check changes quickly.

pushd output
python -m pelican.server
popd

pelpub.bat - the same as pelrun.bat but uses the settings in the publishconf.py file.

pelican content --output output --settings publishconf.py

As most of your non blogging interaction with Pelican is from the command line, sometimes you want to see how your post will look on the actual site. This could involve changing your post multiple times, publishing it and reloading the server. One handy DOS command that will make this easier is the start command. It runs the batch file in a separate process. This way you can quickly publish your post while the server is still running and in a few seconds see it in the browser.

start pelrun
start pelserve

When publishing:

start pelpub

Custom Theme

Although Pelican has a plethora of themes, chances are even the best will be 90% of what you want. There has to be some customisation at some point. I decided to take the long approach and build my theme from scratch. By "from scratch" I mean get the most basic theme and then build on it. Out of the box, Pelican gives you a basic template with all the variables which can be used as a basis to build your very own theme bottom up. The original installation of Pelican already comes installed with 2 themes. These are the notmyidea and simple themes. The most basic them I could find was the simple theme because this has the least customization and therefore is the best theme you can build upon.

  1. Create a directory named themes in the root folder.
  2. Copy the simple theme from that has been installed with the Pelican package. This should be located in venv\Lib\site-packages\pelican\themes if you have installed a virtual environment in the setup above.
  3. Paste it in the new themes directory you created.
  4. In both the pelicanconf.py and publishconf.py, include a setting THEME='themes/simple', which points to the theme you can modify.

Good luck making your own customized theme. If you are someone like me, there will always be improvements to make that will keep you awake at night as they are not perfect enough.

Markdown with code highlighting

I blog about all the things I am interested in. Mostly business, technology and statistics. Articles could include analysis of data and writing scripts to process data. I wanted to create content without having to worry about styling and also wanted to put in code snippets and make them come out as a user might see them on their computer. The Pygments package provides beautiful code highlighting and set up is quite easy. Once done you don't have to worry about it. To include syntax highlighting, simply include the css file that is generated by Pygments.

pygmentize -S monokai -f html -a .highlight > pygment.css
cp pygment.css path/to/theme/static/css/

The css file gives you the highlighting for each of the elements of your code samples. The result of this is beautiful code highlighting which even recognizes the language you use when doing the highlighting.

Latex for math equations

Nothing completes the explanation of a statistical process like a pretty math equation. Trying to create even a simple equation using text is fraught with misunderstandings. LaTex is a language to construct mathematical formulas via text. The text follows rules which are then used to beautifully format mathematical equations. There is a simple Pelican plugin that does this for you. Pelican has a considerable list of plugins which are programs to add functionality to your blog. One of these are the render_math plugin that takes a formula like:

x^2 + y = z

and turns it into

$$ x^2 + y = z $$

All the plugins are available on github. Installing plugins is simple. Clone the repository and point to the plugin you want to use in your config file.

git clone --recursive https://github.com/getpelican/pelican-plugins
PLUGIN_PATHS = ['path/to/pelican-plugins']
PLUGINS = ['render_math']

Pi looks so much better as

$$\pi$$

.

Host on Amazon S3 as a Static Site

Amazon S3 is a great low cost option for hosting a fully functional website. Static hosting on Amazon has been around since forever and there are a great set of tools to streamline the process of uploading new posts onto the blog. One of the less discussed advantages of static hosting on Amazon is that in case your blog becomes suddenly very popular, S3 will easily scale up to accommodate.

I will be using the S3CMD program that lets you upload files to your S3 bucket directly from the command line.

Everything you need to know 1. https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html 2. http://s3tools.org/s3cmd-howto

The pelpub.bat file can be modified to streamline the process of uploading the new site the S3 bucket when you have new content. pelpub.bat

pelican content --output output --settings publishconf.py
python C:\Users\Karim\Documents\s3cmd\s3cmd del s3://findingpatterns.co.uk/**
cd output
python C:\Users\Karim\Documents\s3cmd\s3cmd put --recursive . s3://findingpatterns.co.uk
cd ..

In order to have a clean upload since files move around a lot, it is worthwhile deleting what is already there before uploading the new batch.

The Ability for Users to Comment on Posts

The blog uses Disqus to handle user comments. First set up an account and go through the process of adding comments to your website. There is currently a list of platforms and the associated coding that you need to inject into your html pages but Pelican isn't on this list. Because if this, you need to use the Universal Code option. This will give you the necessary HTML and JavaScript to be included. As I only want comments only to be created at an article level, I have included this code only in the articles.html template.

<div id="disqus_thread"></div>
<script type="text/javascript">

    var disqus_config = function () {
    this.page.url = "{{SITEURL}}/{{article.url}}";  // Replace PAGE_URL with your page's canonical URL variable
    this.page.identifier = "{{article.title}}"; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
    };

    (function() { // DON'T EDIT BELOW THIS LINE
    var d = document, s = d.createElement('script');
    s.src = 'https://findingpatterns.disqus.com/embed.js';
    s.setAttribute('data-timestamp', +new Date());
    (d.head || d.body).appendChild(s);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

The variable page.url and page.url.identifier will be updated using Jinja variables which will be created for each article when the pages are being constructed.

Don't forget the HTML you need to put in before the end of your body tag:

<script id="dsq-count-scr" src="//findingpatterns.disqus.com/count.js" async></script>

Version Control

Although this is a given for all software projects, I thought I would put in how I have used this to streamline publishing. Basically, I want to be able to write content and make changes to the site on any computer. I also want an automatic backup every time new content is published. I have installed git and have created a repository on github. In the batch files for publishing, I have added commands to update the repository with the changes made. This way I don't have to think about my repository being updated.

Other Important Points

It's taken a while to come up to this point. I am pleased with the look of the site and think it's a good addition to my online portfolio. Since my site was up only recently, every time I learn something new, I will come back to this post and add it to the relevant area. The final objective of this blog was to finish the technical stuff all in one go so that I could eventually only focus on the content. I would like to hear your thoughts so please get in touch.

Glossary and References

Markdown - Text formatting to publish to HTML. Read about it here.

Virtualenv - Useful Python package used to isolate packages installed in projects from other projects.

Jinja - Template engine for Python which is used by Pelican to generate pages. Also used in app development.

Pygments - Code syntax highlighting. Full documentation on the website.

GIT - Version control system for software projects.