wiget.github.io

---

Example nikola website using GitLab Pages.

Learn more about GitLab Pages at https://pages.gitlab.io and the official documentation https://docs.gitlab.com/ce/user/project/pages/.

---

Table of Contents generated with DocToc

• GitLab CI
• Building locally
• GitLab User or Group Pages
• Did you fork this project?
• Troubleshooting

GitLab CI

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

image: registry.gitlab.com/paddy-hack/nikola

test:
  script:
  - nikola build
  except:
  - master

pages:
  script:
    - nikola build
  artifacts:
    paths:
    - public
  only:
  - master

This uses the registry.gitlab.com/paddy-hack/nikola 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 registry.gitlab.com/paddy-hack/nikola 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 namespace.gitlab.io, 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.

  only:
  - 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.

Troubleshooting

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 conf.py 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 conf.py is already updated to build in the public directory.

3. I get a strange lexer exception

   You are probably using extensions that require software not included in the registry.gitlab.com/paddy-hack/nikola image. For example, if your site has Ipython/Jupyter posts (that is, .ipynb format via POSTS or PAGES in conf.py ) GitLab build won’t be able to compile them, even if you locally can.

   The registry.gitlab.com/paddy-hack/nikola 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

    pages:
      script:
        - pip3 install jupyter
        - nikola build
   

---

Forked from @sukiletxe