This article shows you how to set up a fully functional blog with Jekyll and publish it on GitLab Pages in just five minutes.

The result will initially be a copy of this blog—but entirely under your control. You can then customize the design, remove or add pages and posts as you wish.

A big advantage: Thanks to CI/CD on GitLab, all you need to do is save your changes, and everything else happens automatically!

Step-by-Step Guide

Registration and Basic Setup

  • If you don’t have an account yet, sign up for GitLab.

  • Create a new group.

    • The <groupname> you choose here will become part of your blog’s URL later (e.g., <groupname>.gitlab.io, see also the examples in the GitLab documentation).

    • The group’s visibility can be set to Private, even if the blog itself should be publicly accessible later.

    • Alternatively, instead of creating a new group, you can continue using your GiltLab username as the group name. The corresponding namespace is set up during the registration process.

Setting Up the Blog

  • Fork the quickstart-blog repository.

    • This repository already includes a complete configuration, so your blog will be fully operational out of the box.

    • It uses the jekyll-theme-endless theme, which includes full support for AsciiDoc and features such as rendering mathematical formulas and generating a tag cloud.

  • During the forking process:

    • Rename the repository (i.e., "Project name") to e.g., "<groupname>.gitlab.io" or "My first Blog".

    • Choose the <groupname> you created (or your username) as the namespace.

    • You must change the project slug to <groupname>.gitlab.io.

      Important: The Project slug for the repository path is generated automatically based on the Project name. GitLab replaces dots (.) in the name with dashes (-). If you use <groupname>.gitlab.io as your project name, make sure to change the dashes in the Project slug back to dots. For example, update <groupname>-gitlab-io to <groupname>.gitlab.io to ensure the correct repository path.

    • You can set the repository visibility to Private if you don’t want the code to be publicly available. This setting only affects the code visibility and not the visibility of the blog.

Enabling GitLab Pages

  • Under Settings  General  Visibility, project features, permissions ensure that the value for the visibility of "Pages" is set to Everyone if you want your blog to be publicly available.

  • For more details, see the documentation: pages_access_control.

Publishing

  • Trigger the CI/CD pipeline by making and saving a change to any file of the repository. For example, you can use GitLab’s online editor to add your contact information to _config.yml or update the blog’s title.

  • GitLab will automatically start the CI/CD pipeline and publish your changes.

  • DONE! (visit <groupname>.gitlab.io to see your blog live)

Troubleshooting

If I enter <groupname>.gitlab.io, I am redirected to a more complex domain.

Disable the Use unique domain setting under Deploy  Pages  Deployments  Settings to ensure your blog will be accessible at <groupname>.gitlab.io.

If Use unique domain is enabled, the blog might instead be available at e.g., <groupname>-gitlab-io-123456.gitlab.io (see GitLab Pages default domain names and URLs).

Next Steps

After setting up the blog, you can customize it and add content.

  1. If you want to edit your files locally, clone the repository to your computer. You can then use your favorite text editor to make changes. Afterwards commit and push your changes to GitLab to trigger the CI/CD pipeline.

  2. Adjust the settings in _config.yml to tailor the blog to your needs. Refer to the descriptions in the file to see what you can modify.

  3. Create your own posts and pages in the _posts/ and _pages/ directories. If you have Ruby installed locally, you can use two scripts (pa.rb and po.rb) to help you generate files containing typical boilerplate code:

    • ./pa.rb "Page Title" creates a page in _pages/.

    • ./po.rb "Post Title" creates a post with the current date in the _posts/ directory.

    • Edit the template-code in these two files to match your needs.

  4. Learn the AsciiDoc syntax to format the content of your pages. Check out the following:

  5. Customize the design by making changes in the _sass/user.scss file.

  6. Add descriptions for tags. These descriptions are displayed in the glossary and on tag pages. Check out and adapt the data in the file _data/tag-descriptions.yml.

  7. Remove example pages from this blog—most are located in directories prefixed with can-be-removed_.

  8. Run the blog locally on your own computer.

    • Install Ruby.

    • Install Bundler: gem install bundler.

    • Install dependencies: bundle.

    • Start the Jekyll server: bundle exec jekyll serve.

    • Visit http://localhost:4000 to test your blog locally.

  9. Replace default elements of the blog with your own. To do this, create the corresponding files in the _includes/ and _layouts/ directories. Start e.g. with _includes/aside_info.html. For available options and implementation details, refer to the jekyll-theme-endless documentation. From this point on, it makes sense to familiarize yourself with Jekyll and Liquid.

Additional Steps

  • If you wish, you can remove the "Fork relationship" (Settings  General  Advanced  Remove fork relationship and click "Remove fork relationship"). However, I recommend keeping the relationship if you intend to contribute to this quickstart guide or wish to benefit from its updates.

Further Reading