HealthPoliticsEconomics | Quant Analytics | Numerics

A Python Website & Blog with Pelican and Jupyter

This post is rather an overview than a detailled tutorial. It summarizes the different steps you have to take to run a Pelican website where you use Jupyter to write the blogs.

Ressource #1 is always http://docs.getpelican.com/en/stable/

Here some other interesting sources: http://marpat.github.io/python-anaconda-and-pelican-on-windows.html and http://nafiulis.me/making-a-static-blog-with-pelican.html

The overall Workflow

This is a general overview over all steps needed until you can run your Pelican website in your local browser. The sections below give some details to the single steps.

  1. Install the pelican software following http://docs.getpelican.com/en/stable/
  2. !pelican-quickstart (starts a new pelican project)
  3. modify pelicanconf.py to choose a theme you like
  4. write an article with Jupyter (see below)
  5. from Jupyter export your article as myArticleName.md or myArticleName.rst
  6. edit myArticleName.md and delete the blanc lines at the top of the files
  7. deposit your articles in directory content as myArticleName.md or myArticleName.rst
  8. Run pelican to transform the content into HTML with!pelican content -s my_pelicanconf.py -t /projects/your-site/themes/your-theme ; or simpler: !pelican content if your configuration file has the default name pelicanconf.py
  9. change to the folder where te output is: !cd ~/projects/yoursite/output
  10. run your local web server !python -m pelican.server ; or alternatively: !python -m http.server
  11. start your browser with http://localhost:8000/ to see the created website

Appearence, themes, pelicanconf.py

The pelicanconf.py file is the controlling configuration file of your perlican website. There are some dozens of prepared themes you can download. Each theme comes with two directories (static, templates). In pelicanconf.py you have to set the path to your choosen theme. It might be helpful that you have a pelicanconf_myTheme.py for each of our prefered theme.

  1. download the pelican themes from http://www.pelicanthemes.com/
  2. place your favorite theme in in your pelican directory and set in pelicanconf_myTheme.py the path and the name. e.g. THEME = 'themes/myTheme'

Write an Article

  1. Use Jupyter to write your article
  2. Write into the first Jupyter cell of your article the pelican head:

    Title: My everything telling title
    Date: 2018-08-03 10:20
    Modified: 2018-08-15 19:30
    Category: Python
    Tags: pelican, publishing
    Slug: my-universal-post
    Authors: John Devil, Lydia Angel
    Cover: /p001/img001/pic1.png
    Summary: All you want to know about pelican
  3. export/transform the Jupyter file to a Markdown file (or to a rST file) with file -> download as

  4. edit the Markdown file and delete the trailing blank line at the top
  5. if not already done: deposit the Markdown file in the content directory

Structure of the Content directory and Categories


You can use the content directory as a classifier which assigns the articles to a category. For that in pelicanconf.py you must set USE_FOLDER_AS_CATEGORY = True. That means that Politics, QuantsNumerics and Technics will appear as categories in your pelican website.

├── content
│   ├── Politics/
│   │   └── pArticle01.md
│   │   └── pArticle02.md
│   ├── QuantsNumerics/
│   │   └── qArticle01.md
│   │   └── qArticle02.md    
│   ├── Technics/
│   │   └── tArticle01.md
│   │   └── tArticle02.md
│   ├── article20.md
│   ├── article21.md
│   └── pages
│       └── AboutUs.md
│       └── furtherProjects.md
└── pelicanconf.py

In the head section of your article you can give explicitely the article a category with Category: Python You can now structure your content directory as you prefer it, e.g. a directory for each article which is helpful if you have pictures and other static files which belong to the article:

├── content
│   ├── p001/
│   │   └── pArticle001.md
│   │   └── img001
│   │       ├── pic1.png
│   │       ├── pic2.png
│   │       └── movie.mp4
│   ├── p002/
│   │   └── pArticle002.md
│   │   └── img002
│   │       ├── pic1.png
│   │       └── pic2.png
│   └── pages
│       └── AboutUs.md
│       └── furtherProjects.md
└── pelicanconf.py

In pelicanconf.py you must set

  STATIC_PATHS  = ['p001','p002',]

How to include Images into the Article

For detaiiled instructions follow this:

In pelicanconfig.py set:

PATH = 'content'
STATIC_PATHS = ['p001','p002']

Open the md-file and have a look where the pictures are. You will find something like output_3_0.png. Replace that by




Add an Image to the Summary

In the Jupyter head section, cover is a picture that is added to the summary in the table of content.

  • if you have images in your article, use Cover: /posts/img001/pic1.png
  • if do not have images in your article, use Cover: /p001/img001/pic1.png

Note that \(posts\) has to correspond to the setting in myPelicanConf.py :

ARTICLE_URL = 'posts/{slug}.html'

and \(p001\) corresponds to the structure of your content directory

In order to include the cover, make an extension there where article.summary already is used. I use pelican-theme alchemy (that uses bootstrap) and article.summary is in index.html. I extended it as follows:

  <div class="col-sm-8">
    <h4 class="title"><a href="{{ SITEURL }}/{{ article.url }}">{{ article.title }}</a></h4>
    <div class="content">
      {{ article.summary|striptags }}
      {% if article.cover %}           
         <div class="container"><div class="col-md-6" style="padding-left: 0px;  padding-right: 0px;">
           <img src="{{ article.cover }}" class="img-fluid">
      {% endif %} 


If you create a folder named pages inside the content folder, all the files in it will be used to generate static pages, such as About or Contact pages.

You can use the DISPLAY_PAGES_ON_MENU setting in pelicanconfig.py to control whether all those pages are displayed in the primary navigation menu. (Default is True.)

If you want to exclude any pages from being linked to or listed in the menu then add a status: hidden attribute to its metadata. This is useful for things like making error pages that fit the generated theme of your site.

Development or production state

During the development we set in _myPelicanConf.py _

#--- development stage ----------------
SITEURL = 'http://localhost:8000' 

Comment out these lines when you want to pblish your site (production) and set in myPelicanConf.py instead

#------ production stage ------------------
SITEURL = 'https://www.myDomainName.com'

Run your Pelican Website

with command line (CMD window)

  1. change to your Pelican project as your current directory
  2. let Pelican transform your content into output withs
  3. pelican content, if your setting file is named as pelicanconf.py
  4. pelican /path/to/your/content/ -s path/to/your/myPelicanConf.py in the general case
  5. run a webserver with python -m http.server
  6. start in your browser http://localhost:8000/ to see the result

with Jupyter and command line (CMD window)

  1. change to your Pelican project as your current directory
  2. in Jupyter run
  3. !pelican content, if your setting file is named as pelicanconf.py
  4. !pelican -s path/to/your/myPelicanConf.py in the general case
  5. have a CMD window open with running a webserver permanentely with python -m http.server
  6. refresh/reload your browser http://localhost:8000/ to see the result

    pelican pyanoB/content -s pyanoB/pelicanconf_alchemy.py

    pelican content -s pelicanconf_alchemy.py

    cd C:\path\to\myPelicanDirectory\output

    python -m http.server



--> see an other post for

- github as publication server
- Discus as an added discussion plattform
- fabric3 for further automatisation