Create a blog with Pelican, hosted on Github/Netlify

Comments

I hope this article / tutorial will give you the essential knowledge and steps to create and deploy your Pelican static blog on Netlify for free !

Goals

  • Install Pelican
  • Create a website running on Pelican
  • Deploy a Pelican based site to Netlify.com

Prerequisites

  • Basic knowledge about git and python
  • Python 3 and git installed on your workstation
  • VSCode or other IDE

Install Pelican

The first step is to create a python virtual environment on your machine and then install Pelican and other necessary dependencies.

I personally use poetry and the command in your terminal would go this way:

> cd /path-to-your-blog-folder
> poetry init

This command will guide you through creating your pyproject.toml config.

Package name [blog]:
Version [0.1.0]:
Description []:  My personal blog
Author [MattiooFR <*****@*****.com>, n to skip]:
License []:
Compatible Python versions [^3.8]:

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file

# a few more lines telling your about the generated config file..

> poetry shell
> poetry add pelican Markdown typogrify invoke livereload
# install happening...
> pelican-quickstart

Welcome to pelican-quickstart v4.2.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

> Where do you want to create your new web site? [.]
> What will be the title of this web site? Your blog title
> Who will be the author of this web site? Your name
> What will be the default language of this web site? [fr] en
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10]
> What is your time zone? [Europe/Paris]
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n)
> Do you want to upload your website using FTP? (y/N)
> Do you want to upload your website using SSH? (y/N)
> Do you want to upload your website using Dropbox? (y/N)
> Do you want to upload your website using S3? (y/N)
> Do you want to upload your website using Rackspace Cloud Files? (y/N)
> Do you want to upload your website using GitHub Pages? (y/N)
Done. Your new project is available at ***/***/Blog

> pelican
# says nothing to generate but it will still generate your empty blog files, congratulation !

Ok, now that we have the skeleton of our blog done we can move on to the next part.

You should see an arborescence that looks like this

.
├── content            # this is where your articles written in markdown for eg will be placed
├── output             # your website will be generated in this folder
├── Makefile           # file for automating generating and publishing tasks
├── pelicanconf.py     # config file for the generation of the output
├── publishconf.py     # also a config file for publishing
└── tasks.py           # file also for the automation part

Now go in your content folder and create a file, for the purpose if this tutorial, here is a markdown file article.

Title: Prime number finder in python
Date: 2020-03-21 16:00
Tags: maths, python
Category: maths
Slug: primes-list
Authors: Mathieu
Summary: Find all the prime numbers in a composite number with python.

## Extract all the prime number from a composite number with python

This is a quick article to show you how to create an algorithm to extract all the prime numbers from a composite number in Python.

### Algorithm

```python
def primes_list(N):
    """
    Extract all the prime numbers
    from a composite number

    Keyword arguments:
    N -- an integer
    Return: a list of prime numbers
    """
    for i in range(N-1, 0, -1):
        if i == 1:
            return [N]
        elif N % i == 0:
            return [int(N/i)] + primes_list(int(i))
```

### Usage

```python
print(primes_lists(12))
> [2,2,3]
```

The first 7 lines will be more detailed in the next article but they are essential for pelican to generate properly your article and are called the metadata.

On your terminal do the command pelican or invoke build (if you installed the invoke package) to generate the files for your new article, and if you now have a look in your blog folder you should see new folders and files.

Lets have a break with a quick explanation on the invoke build command

While following tutorial to learn myself how to use pelican to create a blog, I faced a few issues and I want to prevent you facing the same, while still understanding why.

  • The integrated make *** commands produces errors when your blog folder is located in a path that includes spaces so this was the first pain point.
  • The make build doesn’t output anything, the first time I thought there was a problem with my terminal but it was actually working. I don’t like when things are unclear so this was a second pain point for me.
  • The last and ultimate pain point was that the make devserver is just not working. This command is supposed to automatically detect changes in your file and regenerate your blog.

After looking on the revered google, I discovered that a second command can be used. This is invoke but you need to install a separate package, which is why I made you install it at the beginning. With this new package you could do invoke build to build your blog without the path pain point.

If you want to regenerate your blog when a changes in a file is detected, invoke regenerate or pelican --autoreload is your command.

Alright, that was quite a long break but I think it was necessary !

Let’s see how your blog looks like no ?

For that you need to use the command invoke serve or pelican --listen in your terminal, if your terminal looks frozen don’t worry, it actually works. If you now open your web navigator and go here http://127.0.0.1:8000 your blog should now appear !

Now I will tell you a magical command that require one more package to be installed, it is invoke livereload. If you followed the tutorial, you should already have installed the livereload package.

If you do invoke livereload your blog will be regenerated when a changes is made, AND your browser will be automatically reloaded as well ! Look at that ! Removing the need for you to do cmd + R !

With one terminal windows running your blog will be served, auto regenerated, and your browser will be automatically reloaded each time you save a change in your blog. This is really really useful when you are developing your blog before deploying it to everybody.

Hosting your blog files

Create an account in GitHub if you don’t have one yet.

Next, create a repository called “blog_source”. This is where you will push all your blog files. Once the repository is made do the following command in your terminal at your blog folder location.

> git init
> git add .
> git commit -m "Initial commit"

# change <your_github_name> in the command down below
> git remote add origin https://github.com/<your_github_name>/blog_source.git
> git push -u origin master

Publishing your static blog

Now that you have a beautiful basic blog locally, the next step is to make it available to everybody right ?

Netlify offer the free service of hosting and deploying a free static page blog, and this what pelican is making 💪🏼, a free static page blog. The procedure is quite straightforward.

Register in Netlify, you can signup with your GitHub account. After you signed up, click on create a new site and select Github as a source. You can accept to give only your blog_source repository to Netlify. In the last step you need to provide the command to build your website in the input labeled build command which is invoke build. The published directory is output.

Netlify require a requirements.txt file to properly build your blog. Enter this command in your terminal to export your poetry dependencies to this required file.

poetry export -f requirements.txt > requirements.txt

Now your blog is almost ready, simply commit and push a new change in your blog, like adding a new article, and Netlify will automatically detect a change in your git repository. It will then build your files and deploy your static blog. In the settings you can specify the name of your blog. I personally decided to buy a domain name so I can have my own url like www.brainsorting.com instead of www.brainsorting.netlify.com.

The procedure is to directly buy the domain with Netlify, or buy it through https://domains.google/ and then follow the instruction in Netlify to use that domain.

Writing articles

The power of Pelican is that you can write in markdown, reStructuredText or directly HTML and then it will be generated in the same output format, HTML. For writing in Markdown you need to have the parser package installed, which is done with a quick pip install Markdownor poetry add Markdown.

It is really helpful to add images, and to do so when writing in Markdown you need to follow those instructions.

Create a new folder images in your content folder.

Open the pelicanconf.py file and add this line STATIC_PATHS = ['images']. This is telling Pelican to include the folder images in the output when building your blog.

Now you can write ![your_image](/images/your-images.png) in Markdown and get your image displayed.

Choosing a theme

You can choose a pelican theme here. Then store the theme somewhere in your blog folder, create a THEME variable in your pelicanconf.py file and set it to the location where you downloaded your theme in your blog folder.

Installing the Jupyter Plugin

This plugin enables the support for .ipynb file. Create the plugins folder. Run the git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb command to add the plugin as git submodule in this folder.

Be sure to have these lines in your pelicanconf.py :

MARKUP = ('md', 'ipynb')

PLUGIN_PATH = './plugins'
PLUGINS = ['ipynb.markup']

Copy the notebook file into the content folder.

Create a file that has the same name as your notebook, but with the extension .ipynb-meta.

Add the following content to the ipynb-meta file, but change the fields to match your own post:

Title: Jupyter notebook
Slug: jupyter-post
Date: 2020-07-11 20:00
Category: posts
Tags: python pelican
author: mathieu dugue
Summary: Test jupyter notebook

Each time you want to add a new notebook you need to repeat those steps.

Useful Modules

References

Comments

Comments powered by Disqus