Gitlab Pages Simply Put

Yet another topic IMHO explained in the most possible complicated way in Gitlab documentation, Gitlab pages are in fact extremely powerful and simple to use.

In order to create a website with an URL of the form https://<username>.gitlab.io/<project>, there are a couple of steps to follow. First, write a Job to publish your pages, this job can be part of your project’s .gitlab-ci.yml but for some reason, official documentation gives the idea you are supposed to create a specific repository for that.

The only important thing to understand is that the website is actually the product of a Job‘s artifacts (just like binary releases in my previous article on Gitlab) which must be created in a directory called public. Also mandatory is the name of the Job, which must called pages. That’s as simple as that. Now here’s an example of such a Job:

pages:
  image: debian:buster-slim
  stage: release
  script:
    - apt-get update -qq && apt-get -qq -y install curl jq
    - /bin/sh pages/mkpages.sh
  artifacts:
    paths:
      - public
  when: manual
  only:
    - master

In short:

  • I use a smaller image than the one use to build the main project’s executable and tests
  • link the Job to the release phase
  • install curl and jq which I use to generate the website
  • execute a script of mine (see below) to append some data
  • declare the artifact's path
  • set that this Job is manually triggered
  • set that this Job should only appear in the master branch

Another idea suggested by the official documentation is that you should clone an existing pages project and use some kind of static website generator to build your website. Here I simply use a script to generate a website from the project’s README.md file:

#!/bin/sh

read web_url avatar_url << EOCURL
$(curl -s "${BASEURL}"| jq -r '.web_url + " " + .avatar_url')
EOCURL
link="<a href=\"${web_url}\" class=\"lead\">&nbsp;&gt; Go to project's Gitlab</a>"
rm -rf public
mkdir -p public
cp -f pages/index.html pages/bootstrap.css pages/monokai.css public/
sed "3 a <img width=\"40\" src="${avatar_url}"> ${link}\n" README.md \
  >public/README.md

The index.html file which is copied in the public directory is like this:

<!doctype html>
<html lang="en">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    <!-- Bootstrap CSS -->
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
    <link rel="stylesheet" href="bootstrap.css">
    <link rel="stylesheet" href="monokai.css">
    <script src="https://code.jquery.com/jquery-3.3.1.min.js" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
    <script>
      $.get("README.md", function(data) {
         out = marked(data);
         $('#content').html(out);
      });
    </script>

    <title>Goxplorer, a Bitcoin blockchain explorer</title>
  </head>
  <body>
    <div id="content" style="padding: 3em;"></div>
  </body>
</html>

Apart from the bootstrap boiletplate, the important bit is the inclusion of marked, a markdown parser and compiler written in javascript / nodejs which will read the README.md and inject the resulting HTML into the index.

Here’s the link to the mentionned pages templates.

Now, why bother creating a website only to create a website from the README.md file which is already rendered in the project’s homepage you may ask? Well because for a reason I don’t yet get, Gitlab project’s SEO is really bad compared to Github‘s, so I thought maybe with a standard, classic website using the same content but formatted like an actual website, search engines would be happier. I’ll keep you posted with that.