Example Nikola site using GitLab Pages:

Name Last Update
files Loading commit data...
galleries/demo Loading commit data...
images Loading commit data...
listings Loading commit data...
posts Loading commit data...
stories Loading commit data...
templates Loading commit data...
.gitignore Loading commit data...
.gitlab-ci.yml Loading commit data... Loading commit data... Loading commit data...

Build Status

Example nikola website using GitLab Pages.

Learn more about GitLab Pages at and the official documentation

Table of Contents generated with DocToc

GitLab CI

This project's static Pages are built by GitLab CI, following the steps defined in .gitlab-ci.yml:


  - nikola build
  - master

    - nikola build
    - public
  - master

This uses the Docker image, which provides Nikola with all its extras, to build the site.

Building locally

To work locally with this project, you can follow the steps below:

  1. Fork, clone or download this project
  2. Install Nikola
  3. Generate the website: nikola build
  4. Preview your project: nikola serve
  5. Add content

Read more at Nikola's documentation.

Alternatively, you can use the Docker image. See the associated project's README for more information.

GitLab User or Group Pages

To use this project as your user/group website, you will need one additional step: just rename your project to, where namespace is your username or groupname. This can be done by navigating to your project's Settings.

Read more about user/group Pages and project Pages.

Using a different branch

If you keep code on the master branch and want the website on a different one, for example a blog branch, then you must make the corresponding change on the pages job in the .gitlab-ci.yml file.

  - blog

Did you fork this project?

If you forked this project for your own use, please go to your project's Settings and remove the forking relationship, which won't be necessary unless you want to contribute back to the upstream project.


  1. CSS is missing! That means one of two things:

    Either that you have set up the CSS URL in your templates incorrectly, or your static generator has a configuration option that needs to be set explicitly in order to serve static assets under a relative URL.

  2. Building passes but deploy stage fails.

    Nikola's default configuration will by default build the site in the output directory, but GitLab expects it in public. So you must change OUTPUT_FOLDER = "public" in or deploying will fail.

    Alternatively, you can add mv output public in the .gitlab-ci.yml file after the nikola build line.

    If you cloned this project as your starting point, then is already updated to build in the public directory.

  3. I get a strange lexer exception

    Build fails You are probably using extensions that require software not included in the image. For example, if your site has Ipython/Jupyter posts (that is, .ipynb format via POSTS or PAGES in ) GitLab build won't be able to compile them, even if you locally can.

    The image includes the nikola[extras] but not any additional software (like ipython, pandoc, latex, or any software you may have on your local system) that your extensions may require.

    The fix is to install any extra software you need before building. In the case of .ipynb support, edit the .gitlab-ci.yml file and change

        - pip3 install jupyter
        - nikola build

Forked from @sukiletxe