How to Publish To GitLab Pages

Documentation as a game changer.
Author

Sjoerd de Haan

Published

January 29, 2025

Clear documentation is a game changer in data science. Learn how to publish your websites to GitHub Pages.

Visibility can be the difference between a project that is used and one that is ignored. Sharing work makes you and your team more productive. Putting websites, docs, and dashboards online in minutes is a tool that you want to have in your toolbox.

GitLab Pages

In this post, I show you how to publish your projects to GitHub Pages.

Tech stack

There are a couple of choices to consider when publishing your project website:

  • Static site generator to use
  • Hosting platform to use
  • Render locally vs on CI in the cloud

Static site generators

Static site generators let you publish quickly. They are a game changer. A landing page, project page, blog, or documentation can be created in minutes.

There are tons of static site generators that each have their own strengths and weaknesses. I used Pelican, Hugo and MkDocs in the past. But I found that Quarto is the best for data science projects.

  • MkDocs for product documentation
  • Hugo for landing pages, documentation, and blogs
  • Pelican for blogs
  • Quarto for all above when you generate figures, code, notebooks, and citations

Quarto

Quarto is a static site generator that is designed for data science. It is built on top of Pandoc and Markdown. This makes it easy to publish not only your writing, but also figures, code, notebooks and citations. You can also use it to create interactive dashboards and web apps.

Hosting

You can use any hosting platform. Today I show how to use GitLab Pages.

GitLab offers free Pages is a free service that lets you host static websites directly from a GitHub repository.

Final workflow

There are several workflows to get your project page published.
Here we go for a simple setup:

  1. Render your project locally (quarto publish)
  2. Copy the rendered site to a dedicated branch (quarto publish)
  3. Push the branch to GitHub (quarto publish)

The only command that you need to remember is quarto publish.

GitHub Pages Setup

Assumptions

  1. You work with a git repository
  2. Your main branch is main
  3. Your GitLab remote is origin
  4. You have a Quarto project in the root of your repository
  5. quarto render produces a website

Create an empty branch gl-pages

First make sure all changes are committed. Check with git status.

git checkout --orphan pages
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising pages branch"
git push origin pages

CI/CD

Add a .gitlab-ci.yml file to the root of the pages branch

stages:
  - deploy
deploy-pages:
  stage: deploy
  script:
    - echo "Deploying site from pages branch"
  pages: true
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "pages"'

Push the changes to the pages branch

Setup GitLab Pages

  1. On you GitLab project page, open Settings -> Genereal -> Visibility, project features, permissions enable pages and set access control.
  2. Trigger the CI/CD pipeline by pushing to the pages branch.
  3. On you GitLab project page, go to Deploy -> Pages to set up the domain name.

Automate with a Makefile

.PHONY: publish

# Publish to gitlab pages
publish:
    echo "Publishing to gitlab pages"
    quarto render
    git checkout pages
    rm -r public
    mv _site public
    git add public
    git commit -m "Publish to gitlab pages"
    git push origin pages
    git checkout main

Now run make publish to publish your project to GitLab Pages.