This lesson is in the early stages of development (Alpha version)

Building Websites with GitLab


Before following this lesson, learners should ideally be able to:

  1. create a project on GitLab.
  2. clone a local copy of a project with Git, add and commit modified files, and push/pull changes between local and remote repositories.
  3. execute commands in the shell.

None of the prerequisite above is absolutely necessary to follow the lesson. They will, however, be necessary to efficiently manage the website development from your laptop and test how it looks before creating official versions.

If you’d like to learn any of the skills listed above, the Software Carpentry lessons on the Shell and Git are a good place to start.

For those already familiar with the ways that Git and an online platform like GitLab or GitHub can help them track and compare changes to flat text files and collaborate with others on projects, GitLab (and GitHub) Pages provide a cost-free way to build and host webpages. This approach is commonly used to provide documentation on software projects, and to create blogs and websites for individuals and organisations already used to working with the Git toolset for their other projects. However, for those taking their first steps towards building sites like this, the process can be confusing and intimidating. This tutorial aims to address this, by

  1. providing a step-by-step guide to creating a collection of pages,
  2. showing multiple examples of how to structure them into a coherent site,
  3. demostrating how to use multiple frameworks for web pages development, from plain HTML to Jekyll and Sphinx.

The difference between GitLab and GitHub pages development will also be briefly discussed.

Outdated Screenshots

Throughout this lesson we will make use and show content and screenshots from As an ever evolving platform, GitLab is always adding new features and new visual elements to its website. Screenshots in the lesson may then become out-of-sync, refer or show content that no longer exists.

If during the lesson you find screenshots that no longer match what you see in your browser, please open an issue describing what you see and how it differs from the lesson content. Feel free to add as many screenshots as necessary to clarify the discrepancy.

Learning Objectives

After following this lesson, learners will be able to:

  • create formatted page content with HTML or Markdown
  • configure their project to build and serve pages on GitLab
  • build a simple site to host content in plain HTML
  • build a coherent site with multiple pages using a Jupyter Book
  • customise the layout and style of the pages on their site


Setup Download files required for the lesson
00:00 1. Introduction What is static web content?
Why should I use GitHub or GitLab Pages to create my website?
00:00 2. Authoring With Markdown How can I write content for my webpages?
How do I link to other pages?
00:00 3. Hosting Pages on GitLab How do I publish my pages via GitLab?
00:00 4. Work with Jupyter books locally How do I use Jupyter books to generate a book-like website with chapters?
00:00 5. Host Jupyter Books in GitLab How do I publish a Jupyter book in web pages through GitLab?
00:00 Finish

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.