GitLab Pages Walkthrough

Created for DLN Community

Ryan Walter from the DLN community has a great video on front page linux that shows how GitLab can be used to host a static website. I thought that since DLN is doing a weekly tip on git, it would be a great time to try and show case that and create companion documentation for Ryan’s video.

GitLab does have its own documentation but I hit several snags when trying to follow it while Ryan’s worked seamlessly.

This guide is going to assume that:

  1. You have a GitLab account
  2. SSH Keys are used between origin and master
  3. git is installed on your host computer
  4. Basic git commands are understood so that explanations for every command are not needed.
  5. The ability to install the package hugo on your host machine for testing purposes.

If these assumptions are correct, then the difficulty of this tutorial is estimated to be 2 out of 10. If you don’t have the required knowledge for these assumptions, check out my previous walkthough that follows the DLN tip of the week for git. Ryan uses Fedora for package installation and my guide will be using Ubuntu so there may be slight contradictions between his video and the guide.

Setup

I will be using the same file hierarchy as my previous guides but will be creating a new folder called hugo. The packages for hugo will be installed and git will be initialized for this repository.

  • /home/rastacalavera/git
  • mkdir hugo
  • cd hugo
  • sudo apt install hugo -y
  • hugo new site ./
  • git init
  • git add *
  • git commit -m "first commit

The next set of commands will download the Beautiful Hugo theme and allow you to preview it locally in your web browser.

  • cd themes
  • git submodule add https://github.com/halogenica/beautifulhugo.git beautifulhugo
  • cd ..
  • cp -r themes/beautifulhugo/exampleSite/* ./
  • hugo serve

Now you can see the website in your browser by going to http://localhost:1313/

Close down the server using CTRL+c, commit your changes and push the project to GitLab:

  • git add *
  • git commit -m "working website"
  • git push -u git@gitlab.com:YOURACCOUNTNAME/hugo.git master

Front End Changes

Now we’ll step away from the commandline for a bit and work in the browser on GitLab.

We want GitLab to update our changes automatically so we need to setup the CI/CD file so that our container will be rebuilt with each push.

CICID yml

Now, the settings of your page need to be set to public. visable1 visable

Finally, we can see the site url and visit the page

settings brokensite

The website looks a little broken, that’s okay though, we are going to fix it!

Back to the commandline

Time to return to our commandline prompt in our hugo folder. First we are going to pull down all of our front end changes.

  • git pull

Now we edit our config.toml file:

  • nano config.toml In the first line, you need to put your GitLab url of your website between the " " so for instance mine looks like this:
baseurl = "https://rastacalavera.gitlab.io/hugo2/"

Now, push up the changes:

  • git add *
  • git commit -m "new url"
  • git push

You can watch as your job is run by git hub pipeline

When it is complete and you refresh the website page, it should look like the one you previewed on your main machine. nicesite

All of the actual page content is available in the post folder:

git/hugo/content/post

At ~23 minutes, Ryan deletes all the local files using rm * in the post directory. This doesn’t actually delete them from the main repo and those pages will still be present on the home page. To delete them completely git rm * must be used.

Now you can create your own markdown file for the website with the yaml header included.

---
title: My First Post
subtitle: learning Hugo
date: 2020-12-22
#publishdate:
#draft:false
#expiredate:
#author:
---
# this is where you can experiment with markdown

When done, add your files and push them up.

  • git add *
  • git commit -m "remove template and add original content"
  • git push

Once the job is complete on GitLab, then you’ll need to refresh your changes and everything should look different.

Side note

If you want to add images into your website, the easiest way to get started is to place them all into the static folder. Once your images are in there, you can reference them using markdown like so:

![Sometext](/DLNhugo/imagename.png)

Notice that the static folder is not in the path and the end of your public URL is there. It took me hours to troubleshoot this so hopefully this saves other people a step.

Resources