GitLab Pages is a nice way to host documentation web pages for your research group. This document details ARCC’s supported way of creating a new project for the intent of creating a project just for documentation. NOT adding documentation to an existing project. Any use of Pages outside of this supported way is considered ‘best effort’.
This document assumes that you already have an ARCC GitLab login and have logged in at least once already.
If you already have been able to login to gitlab.arcc.uwyo.edu, please follow the following steps to get started with Pages:
Step 1) Login to the ARCC GitLab instance and create a group
We recommend creating a new Group to host this project. The name of this group, will show up in the URL of every web page you create, so please be mindful of the name you are going to give this group.
WARNING! If you do not first create a group before creating your project, your username will be displayed in the public URL.
For demonstration purposes only, we are going to use ‘pages-example’ as the group name. Please use a group name that is meaningful for you as it will be displayed in a browsers URL.
Also notice that we are keeping the group visibility as private, we will get to how pages makes documents public later on.
Step 2) Import a Project
The second step is to import a project that is already published by GitLab to get the necessary files to host the web pages. We recommend this because creating a blank project and configuring the project to render files as public web pages is a multi-step process that has several failures before it works.
While in the group we just created, start by clicking the ‘New Project’ button.
Then on the next page, click ‘Import project’.
Then we recommend to do the import by using the Repository by URL.
Before finding a URL to import a project from, you must first make a choice on how you want to create and manage your public web pages. There are many options but we recommend two:
Using HTML and other web markup languages like CSS and JavaScript to manage the functionality
Sticking with GitLab’s native markdown using mkdocs
Mkdocs using markdown - https://gitlab.com/pages/mkdocs
The remaining examples will be using markdown with mkdocs instead of providing all the other options. Using the link above, we copy and paste it into the section that asks for the Git Repository URL
Notice that we have to add ‘.git’ to the project URL for it to be valid.
We can rename the project to whatever we’d like, but for this example we will keep the name as ‘Mkdocs’.
We HIGHLY recommend changing this project name to be meaningful for your purposes.
Once again in the visibility section we can keep this project private and click ‘Create project’. How pages get made public will be covered later.
Step 3) Trigger a Runner to Render your site
Once the project has been imported successfully, our documentation pages are not publicly available just yet. We have to make a change before they get rendered.
You’ll notice that there are five files and a directory named docs, by the author of the Published project we imported. DON’T worry that they are authored by someone you don’t know and some of the files haven’t been updated in years.
To start testing to see if everything is working properly, we need to take a look at the mkdocs.yml file.
Please notice that there is a minimal amount of information at the moment. However, this file is VERY important for changing the look and feel of your Mkdocs site, so we will go through each of these three lines.
site_name: My Docs by GitLab Pages
As the name states, this line is the name of your site. Since we imported a published project, this is a generic name. Changing this line is the minimal amount of changes we need to make to make our site public.
site_url: https://pages.gitlab.io/mkdocs
This is the site’s URL of the imported project. We can’t change this at this stage, once we have a public URL we can update this line with the corrected URL.
site_dir: public
This is the directory where we put the content for the site. However, for Mkdocs, it is looking for a ‘docs’ directory, changing this to something else will BREAK the runner. If we want this site to be publicly available, we need to leave this line unchanged. This means we can keep any other files outside of this directory as private and only add directories and files inside of this directory that we want to be publicly viewed.
To take the next step and check out what our site looks like, we need to edit this mkdocs.yml file and change the site name. Click the ‘Edit’ button on the top right and select ‘Edit single file’ to quickly edit this file.
Now we are going to change the site name to something more meaningful for us and commit the changes, this triggers a ‘Runner’.
The Runner is an important concept in GitLab Pages. This runs a job on the system that begins to render the markdown files into HTML. Each time we make commits to our project, it triggers the runner to start the job.
If we change the site name and then commit the changes, we will start to see the job run.
Notice the status of the runner job at the top of the page, with the commit message. If it has a red symbol with an ‘X' the job failed for some reason. Blue means it’s processing, yellow means it’s paused, and green with a check mark means it has succeeded.
Now that we have kicked off this first runner and had it succeed, we can get the first look at our website that we have build using pages.
It’s important to note, that deploying Pages does have a delay from when the changes were made to when they can be viewed.
Sometimes up to several minutes, depending on how complex your documentation site is.
Step 4) Get the site URL
To view your website you’ll need to know where the URL is to copy and paste into a web browser. To do that, please look at the menu on the left side of our project. There will be a drop down menu section that says ‘Deploy’. If we expand ‘Deploy’ we can see the section called ‘Pages’. That is where we will look for our URL. Please click on ‘Pages’
Once we get to the Pages section of our project, we see our URL that looks like pages.arcc.uwyo.edu/<group name>/<project-name>.
Now if we click the link we can get to our site.
Step 5) Update the mkdocs.yml file and add content
We have a site built, but none of the content we may want has been added. To do that, we have to go back to our project in GitLab. If we open and edit the mkdocs.yml file again, we can update the site_url setting to show our actual URL. Note that this doesn’t change any content, but it does help with our personal documentation for what our site looks like.
Back on the main project repository, we have the five files we showed before and that one directory called ‘docs’.
Now we are going to open that directory called ‘docs’ and we see a file called ‘index.md’. If we preview that index.md file, we can see content there that is similar to what we saw when we saw out public site.
That is because Mkdocs is looking at this directory for files and directories to render from markdown into HTML for webpages and navigation. In other words:
Markdown files = individual webpages
Directories = Navigation to more webpages
This index.md will serve as the home page for any Mkdocs site you create and you can begin to build your website by editing this page.
Try it for yourself! Add a new directory and call it whatever you would like and then add a file into it that has a ‘.md’ file extension.
Start by clicking the ‘+' symbol while looking at the 'docs’ directory. and select New directory
Then click into that new directory and use the '+' symbol to add a new file.
Once the runner finishes and the job has had time to render the new pages you can go back to your site and see the new directory in the navigation and the new file as a page.
Any images you want on your webpage also have to be within the ‘docs’ folder. We recommend that for any images that you want to use are included in a new directory within the directory of the page that you want them to be displayed on. For example: ‘docs’ → ‘New-pages’ → ‘images’.
And then you can upload images into the directory to be used by the markdown page by clicking the ‘+' sign and selecting 'Upload a file’.
Now to get this image to render on my new page, I need to use markdown syntax to include it, by editing my new-page.md file.
Once we commit this change and give the runner time to finish, we should see this on our public web page.
This might take a few minutes. Refresh the web page periodically until you see the image show up.
Optional Step 6) Theme Customization
Now we can do a lot to customize how our site looks using the mkdocs.yml file. There are many, many published themes that work with mkdocs, one of the most popular is called ReadTheDocs. This theme is really easy to add to our site. Simply go back to the main project repository and edit that mkdocs.yml file like we have twice already so far and add a new line that looks like:
theme: readthedocsNow commit the changes and wait for the runner to finish the job. Once you refresh the webpage, you can see the theme applied.
Check out alternate themes on the mkdocs repository wiki, or you can attempt to create your own if you would like!
Important Reminders about using ARCC’s GitLab
GitLab is a collaborative space for UWyo researchers to share code and other information, please keep this in mind when creating websites using Pages and be mindful of who you allow to edit the pages.
GitLab is NOT a place to disseminate research data. Projects on ARCC’s GitLab instance will be routinely monitored for how much storage they are using and any project that is using an excessive amount of storage will be asked to reduce it or risk removal from GitLab.
Any use of this service that is not related to research will risk being removed. Please review the ARCC acceptable use policies.
You are free to use any of the Pages functionality you can find, but we recommend using the examples published on the GitLab documentation.