Create a blog with Pelican, hosted on Github/Netlify
Published: 2020-07-18 16:52:30

*Original article : https://brainsorting.dev/posts/create-a-blog-with-pelican/*
<!--
.. title: Create a blog with Pelican, hosted on Github/Netlify
.. slug: create-a-blog-with-pelican
.. date: 2020-07-18 16:20:03 UTC+02:00
.. tags: python, pelican, blogging
.. category: tutorial
.. link:
.. description: Full tutorial on how to start blogging with a static website generated by the Pelican python package.
.. type: text
.. medium: yes
.. devto: yes
.. previewimage: /images/pelican.jpeg
-->

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](http://netlify.com/)

**Prerequisites**

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

<!-- TEASER_END -->

## 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](https://python-poetry.org/) and the command in your terminal would go this way:

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

```bash
.
├── 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.

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

    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

    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](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](https://github.com/join?source=header-home) 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.

```bash
> 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](https://app.netlify.com/signup), 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.dev](http://www.brainsorting.dev) instead of www.brainsorting.netlify.com.

The procedure is to directly buy the domain with Netlify, or buy it through [https://domains.google/](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 Markdown`or `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](http://pelicanthemes.com). 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](https://github.com/danielfrg/pelican-ipynb) 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` :

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

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

- [Katex in Pelican](https://github.com/cqql/pelican-katex)
- [Pelican plugins](https://github.com/getpelican/pelican-plugins)

## References

- [Official website of pelican](https://docs.getpelican.com/en/3.3.0/)
- [Github of the pelican project with templates and plugins](https://github.com/getpelican)
- [A great Markdown Cheat Sheet for helping writing your articles](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
- [Pelican documentation](https://pelican.readthedocs.io/en/latest/settings.html)
- [Dataquest tutorial to create a data science blog with Pelican](https://www.dataquest.io/blog/how-to-setup-a-data-science-blog/)