GitLab Pages enables users to publish static web content via their repositories' CI/CD pipeline. You can use any static site generator, like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also publish any website written directly in plain HTML, CSS, and JavaScript.

Note
 Pages does not support dynamic server-side processing, for instance, as .php and .asp requires. For more information, see Static vs dynamic websites.

As an example, this how-to page will show you how you could publish your own reveal.js slide deck, using Asciidoctor reveal.js (our first use case to start using GitLab Pages).

Example: Creating an HTML Slide Deck

Let’s start by creating an empty repository: $ git init -b main ~/presentation. This creates an empty git repository directory ‘presentation’ in your home directory. Go inside, and start writing your main presentation file ‘presentation.adoc’ using your favourite editor:

= Title Slide
:revealjsdir: https://cdn.jsdelivr.net/npm/reveal.js@5.1.0

== Slide One

* Foo
* Bar
* World

== Slide Two

A Great Story

[.notes]
--
* tell anecdote
* make a point
--

The above should be sufficiently self-explanatory to create your first slide deck, but this is not an AsciiDoc primer. Please see the documentation if you require more information.

Creating the Pipeline

Assuming you’ve now drafted your first version you wish to publish, it’s time to create your (very basic) CI/CD pipeline. Create a new .gitlab-ci.yml file at the root of your repository:

# The Docker image that will be used to build your app
image: asciidoctor/docker-asciidoctor:latest
# Functions that should be executed before the build script is run
before_script: []
pages:
  script:
    - asciidoctor-revealjs presentation.adoc
    - mkdir public
    - mv presentation.html public/index.html
  artifacts:
    paths:
      # The folder that contains the files to be exposed at the Page URL
      - public
  rules:
    # This ensures that only pushes to the default branch will trigger
    # a pages deploy
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

The above basically tells the GitLab Runner to start building this slide deck, using the public asciidoctor/docker-asciidoctor:latest Docker image. It then builds the slide deck using asciidoctor-revealjs available in the Docker image, after which it moves the generated HTML slide deck into a new directory called 'public'. The 'public' directory is not stored in your repository - it will only trigger GitLab to host its contents using Pages.

Push, Build and Publish Your Slide Deck

Now add your remote origin to start pushing to GitLab. This example uses SSH (replace your username): $ git remote add origin gitlab:j.doe/presentation.git

Then push your repository:

user $ git add .
user $ git commit -m 'init'
user $ git push

Once pushed, a GitLab Runner will pick up the new build job, as instructed via the .gitlab-ci.yml you pushed. Meanwhile you can inspect the GitLab Pages settings of your repository (replace your username and repository name): https://gitlab.com/j.doe/presentation/pages

GitLab Pages Repository Settings

It is advised to tick the ‘Use unique domain’ check box, in order to create a working link, without any certificate errors due to dots in our usernames. Click on 'Save changes', refresh the page, and your static site should now be available at the link below the 'Access pages' section.

See here a demo of a slide deck created using reveal.js: https://revealjs.com/demo/

reveal

Conclusion

You should now have a better understanding of what GitLab Pages is, and how to use it yourself. The above is an example to create beautiful slide decks, but you could also use your new skills to publish any other static web content on Pages.

GLHF.