GitLab Pages

GitLab supports Lektor on their GitLab Pages infrastructure. Effectively GitLab can build your website out of any repository on GitLab and hosts it up on either a subdomain or a custom domain (including SSL).

Because this is all supported by the side of GitLab there is nothing you need to configure in Lektor itself other than adding a GitLab config file.

There is also an example project on GitLab with a README you can clone: pages/lektor

Create a Repository

What you need to do to start is to create a new repository for the project on gitlab. There are two types of GitLab pages: user and project pages. User pages are hosted at <username>.gitlab.io and project pages at <username>.gitlab.io/<project>. There can only be one user page and the repository for it needs to be named <username>.gitlab.io.

The branch does not matter. GitLab scans all branches for a file named .gitlab-ci.yml which contains a configuration for gitlab pages.

Configuration

To enable support for Lektor you need to create a .gitlab-ci.yml config next to your .lektorproject file with the following contents:

image: python:latest

pages:
  script:
    - pip install lektor
    - lektor build --output-path public
  artifacts:
    paths:
      - public
  only:
    - master

It's important that the output path is set to public as this is what will be served up. In case you want to use a different branch than master just name the branch differently and adjust the only entry.

Whenever you commit to the repository now, GitLab will automatically start a job on the public infrastructure and deploy your website.

Cache directory

You can enable caching to reuse build results between compilation. To do so, you have to:

set the cache directory using the environment variable XDG_CACHE_HOME;
configure Gitlab to cache this directory.

See the example below.

image: python:latest

default:
  cache:
    paths:
      - .cache/lektor
      - .cache/pip

variables:
  XDG_CACHE_HOME: "$CI_PROJECT_DIR/.cache"

pages:
  script:
    - pip install lektor
    - lektor build --output-path public
  artifacts:
    paths:
      - public
  only:
    - master

CNAME Support

If you want to use a CNAME with GitLab pages you can configure it in the GitLab settings:

Configure CNAME

SSL/TLS Support

If you have an SSL certificate and a custom domain, you can upload your private key and certificate to GitLab and SSL will become available on your custom domain as well.

Configure SSL/TLS

404 Pages

Per convention the file named 404.html is used as placeholder if a page cannot be found. You can create such a page by creating a 404.html/contents.lr file.

This Page