Create GitLab Pages

With GitLab Pages, you can easily publish your own static website directly from your GitLab project. This guide will walk you through the process step by step.

Create a project¶

First, create a new project by following these instructions. Alternatively, you can use our sample project for creating your own static website on openCode, which can be found on this page. The project contains an example of a GitLab page with a customized openCode theme. The basis corresponds to this screenshot and can be changed as desired:

Screenshot der Startseite im Browser

Of course, you can also use other themes or generators, or you can use your own HTML files—this is often the easiest way.

Configure pages¶

The mkdocs.yml file controls the appearance and structure of your website. Customize it as follows:

Set page title¶

site_name: My project name    # The page title can be changed here

Specify project URL and name¶

repo_url: https://gitlab.com/YourUsername/my-website    # URL to the GitLab project (please customize)
repo_name: My project name    # Name of the GitLab project (please adjust)

Include logo and favicon¶

theme:
  logo: assets/logo.svg   # Path to the website logo (please adjust)
  favicon: assets/icon.svg    # Path to the website icon (please customize)

Add your own content¶

The home page of your website is located in the file docs/index.md. Customize the content according to your preferences, e.g., with a welcome message or a short project description.
Customize the legal information on your site:
- Imprint: Edit the file docs/legal/impressum.md.
- Data protection: Edit the file docs/legal/datenschutz.md.
- Copyright notice: Change the entry in mkdocs.yml.
Expand your website with additional pages:
- Create new Markdown files (.md) in the docs/ folder, e.g., about.md for an “About us” page.
- Add the new pages to the navigation in mkdocs.yml:
```
nav:
    - index.md
    - about.md    # e.g., adding a new “About us” page; this list can be expanded as desired.
```

Customizing the design¶

Edit the file docs/style/extra.css to change the appearance of your page. This requires CSS knowledge.
Add images to your Markdown files by adding them to the docs/assets/images/ folder.
Use a glossary: In the includes/abbreviations.md file, you can define terms that are highlighted and explained on your page.

Info

For more information on using and setting up the page, see the Material Theme documentation, which is used by MkDocs (the static page generator).

Here you will find information on extending the functionality of the website, including the following topics:

Customizing navigation
Setting up a blog
Usable extensions
Customizing individual website components
...

Documentation on how to use the built-in plugins can be found on this page.

Setting up the CI/CD pipeline¶

The .gitlab-ci.yml file controls the automatic build and publication of your website. This configuration ensures that your website is automatically built and published every time you push to the main branch.

Create a file called .gitlab-ci.yml in the root directory of your project.
Add the following content:

pages:
stage: deploy
script:
- mkdocs build -d public
artifacts:
paths:
  - public
only:
- main

Frequently asked questions and problems¶

Where can I find the link for my project's website?

After successful setup, you can find your published page at: https://PROJEKT_NAME.usercontent.opencode.de

Alternatively, you can also view the link to your project's website in your project under Settings > Pages.

How can I password-protect a GitLab page?

To create a password-protected GitLab page, follow these step-by-step instructions.