Pelican on GitLab Pages

2017-05-25T22:51:00-05:00

This guide assumes you know how to install software on the computer operating system you are using and you are familiar with the basics of using GitLab.

Getting Started

Required Software

Git - Git or any other Git client.
Python 2.7 or 3.3+ - Python.org
virtualenv - install covered below

Project Setup

Create a repository on GitLab for your new website. It can be public or private, your website will be viewable publicly either way. There are a couple options when creating your site on GitLab. If you create your repository under <username>/<username>.gitlab.io, your website will be available at http://<username>.gitlab.io. This also works for groups, just replace <username> with your groups name. If you create your repository at <username>/<projectname> your website will be available at http://<username>.gitlab.io/<projectname>. Again, this always works with groups, just replace <username> with the name of your group.

Now clone the repository you just created.

$ git clone git@gitlab.com:<username>/<reponame>.git reponame
$ cd reponame

Replace <username> and <reponame> with your username or group name and the name of the repository you created earlier.

If you are using a GUI Git client you need to open a terminal/console window and navigate to the folder you cloned the repository to.

Pelican

After you have your repository created and the required software installed its time to install Pelican.

Install virtualenv

Linux and OS X

$ sudo pip install virtualenv

Restart your terminal

$ virtualenv <path>

Where <path> is the directory you want to save the virtualenv files. Usually something like /home/<username>/virtualenvs/pelican on Linux or /Users/<UserName>/virtualenvs/pelican on OS X.

Whenever you need work in the virtualenv:

$ source <path>/bin/activate

Windows

c:\>pip install virtualenv
c:\>virtualenv <path>

Where <path> is the directory you want to save the virtual env files. Usually something like c:Users<Username>virtualenvspelican

Whenever you need to work in the virtualenv:

c:\> <path>\Scripts\activate

Install Pelican

Make sure your virtualenv is activated and install pelican.

$ pip install pelican markdown

Generate the Base Site

With your virtualenv still active.

$ mkdir blogname
$ cd blogname
$ pelican-quickstart
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? [.] <enter>
> What will be the title of this web site? My Blog <enter>
> Who will be the author of this web site? My Name <enter>
> What will be the default language of this web site? [en] <enter>
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n <enter>
> Do you want to enable article pagination? (Y/n) <enter>
> How many articles per page do you want? [10] <enter>
> What is your time zone? [Europe/Paris] America/Chicago <enter>
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) <enter>
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) <enter>
> Do you want to upload your website using FTP? (y/N) <enter>
> Do you want to upload your website using SSH? (y/N) <enter>
> Do you want to upload your website using Dropbox? (y/N) <enter>
> Do you want to upload your website using S3? (y/N) <enter>
> Do you want to upload your website using Rackspace Cloud Files? (y/N) <enter>
> Do you want to upload your website using GitHub Pages? (y/N) <enter>
Done. Your new project is available at /home/<username>/blogname

For most the most part you can leave all the defaults to the yes and now questions. Make sure to fill in the title of the website, author of the website and time zone.

Setup for GitLab

By default Pelican outputs the generated files to a folder named "output", this won't work with GitLab. Open the file pelicanconf.py and add the following line.

OUTPUT_PATH = 'public'

You can also customize any other options you wish in this file.

Navigate to your repository's Settings, and go to CI/CD Pipelines. Make sure "Shared Runners" is enabled.

In order to tell GitLab we need Pelican installed to build out site, we need to add a requirements.txt file.

pelican
markdown

Next we need to make the configuration file to actually build and deploy our site to GitLab. Create a new file named .gitlab-ci.yml and add the following lines to it.

image: python:3.6-alpine

pages:
  script:
  - pip install -r requirements.txt
  - pelican -s publishconf.py
  artifacts:
    paths:
    - public/

Since we don't have any content written yet, we need to add a .gitkeep file to out content folder. Because Git doesn't track empty directories we add a blank file to our content folder so that it exists when the build tool runs on GitLab's servers. On windows simply make a empty text file and rename it .gitkeep. On Linux or OS X you can do touch content/.gitkeep.

Finally we are ready to test. We must stage the new/changed files, commit them to Git then push them to GitLab where the site is built and published.

$ git add .
$ git commit -m "Inital Commit"
$ git push origin master

Navigate to your project on GitLab and go to "Pipelines". You should either see a task running or completed or possibly failed. If the task is still running just wait till it is complete. If the task fails you can click the "Failed" button and go to "Failed Jobs" and get a build log to help you figure out where it went wrong.

Once the task as completed successfully you should be able to view your site at http://<username/groupname>.gitlab.io or http://<username/groupname>.gitlab.io/projectname.

Adding New/Editing Posts

To add or edit posts just repeat the final step.

$ git add .
$ git commit -m "Some Descriptive Message"
$ git push origin master

Thats it! I hope you found this guide useful.

Segfaulted's Blog