Date Modified Category web Tags web / pelican / gitlab

What is Pelican

Pelican is a static site generator written in Python language. The website content can be written using Markdown markup or ReStructuredText markup.

No particular html knowledge is required.

Installation

There are many ways to install Pelican. You can follow the explanations on the main website: Installing Pelican.

Call pelican-quickstart and answer all the questions:

Welcome to pelican-quickstart v3.7.1.

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? pelican_demo
> Who will be the author of this web site? Pascal Geiser
> What will be the default language of this web site? [English]
> 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) https://pgeiser.gitlab.io/pelican_demo
> Do you want to enable article pagination? (Y/n)
> How many articles per page do you want? [10]
> 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) N
Done. Your new project is available at <your folder>

Running pelican on the created folder will lead to this message:

$ pelican
WARNING: No valid files found in content.
Done: Processed 0 articles, 0 drafts, 0 pages and 0 hidden pages in 0.10 seconds.

Jump into the freshly create output directory and run a simple python server:

$ cd output
$ python -m SimpleHTTPServer
Serving HTTP on 0.0.0.0 port 8000 ...

Open a browser and go to http://localhost:8000/. That’s what you should get:

Pelican empty site

Creating some content

Create a file content/posts/category/first.rst:

First post
##########

:date: 2017-11-25 19:00
:modified: 2017-11-25 19:00
:tags: pelican, web
:authors: Your name here!
:summary: First post with pelican

Pelican rocks!

Edit pelicanconf.py and add:

ARTICLE_PATHS = ['posts']
USE_FOLDER_AS_CATEGORY = True

The final file structure is the following:

site
│   pelicanconf.py
│   publishconf.py
│
└───content
    └───posts
        └───category
                first.rst

The final result should look like this:

Pelican first post

Theme pelican-bootstrap3

I’ve chosen the theme pelican-bootstrap3. It’s up to date and supports a lot of extra features. To install it, clone the repository:

$ git clone https://github.com/getpelican/pelican-themes.git
Cloning into 'pelican-themes'...
remote: Counting objects: 5816, done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 5816 (delta 0), reused 0 (delta 0), pack-reused 5811
Receiving objects: 100% (5816/5816), 29.91 MiB | 292.00 KiB/s, done.
Resolving deltas: 100% (2870/2870), done.
Checking connectivity... done.
Checking out files: 100% (2037/2037), done.

Now copy the folder pelican-themes/pelican-bootstrap3 in your pelican website directory.

Clone the Pelican plugins:

$ git clone https://github.com/getpelican/pelican-plugins.git
Cloning into 'pelican-plugins'...
remote: Counting objects: 4316, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 4316 (delta 1), reused 0 (delta 0), pack-reused 4306
Receiving objects: 100% (4316/4316), 2.40 MiB | 306.00 KiB/s, done.
Resolving deltas: 100% (2010/2010), done.
Checking connectivity... done.

Copy the folder pelican-pluginsi18n_subsites in a plugins subdirectory.

Create a banner picture and put in ‘content/images/banner.jpg’

Edit the file pelicanconf.py and add the following lines:

# THEME CONFIG
THEME = 'pelican-bootstrap3'
JINJA_ENVIRONMENT = {'extensions': ['jinja2.ext.i18n']}
PLUGIN_PATHS = ['plugins']
PLUGINS = ['i18n_subsites']
BANNER = 'images/banner.jpg'
BANNER_SUBTITLE = "Your banner message here."
STATIC_PATHS = ['images']

The final file structure is the following:

site
│   pelicanconf.py
│   publishconf.py
│
├───content
│   ├───images
│   │       banner.jpg
│   │
│   └───posts
│       └───category
│               first.rst
│
├───pelican-bootstrap3
│   ├───...
│
└───plugins
    └───i18n_subsites
        ├───...

And the result:

Pelican bootstrap3 theme

Deploying on Gitlab pages

Deploying on Gitlab pages is well explained in details in the Gitlab documentation:

Pages

To export a simple folder containing html, you need to create a file .gitlab-ci.yml with the following content:

pages:
  stage: deploy
  script:
  - echo 'Nothing to do...'
  artifacts:
    paths:
    - public
  only:
  - master

and make sure the content is in a folder called public. After each commit, a continuous integration pipeline will be executed to export your pages on the Gitlab pages:

Pelican CI pipeline

You can look at the job (even while being executed):

Pelican CI Job

if everything went correctly, you should be able to admire the result on Gitlab pages. In my case: https://pgeiser.gitlab.io/pelican_demo

Pelican result when not using "publishing" settings

But wait… This is not the result we were expecting. In fact, by default, pelican uses relative paths which are easy to use with the python SimpleHTTPServer. For Gitlab pages, you have to use absolute urls. By rebuild using the correct configuration (publishconf.py) and commiting the results, finally the site appeas as expected:

Pelican result when using "publishing" settings

Have fun!