This is a guide on what you'll need to install and run on your machine so you can make edits locally. This is quicker than in the web interface and allows you a better overview and preview when making complex changes.
1. Help is available for team members
If you work for GitLab Inc. we don't expect you to figure this out by yourself. If you have questions ask anyone for help, you're more likely to have success with:
People that have been here longer than 3 months, the team page lists people in order of how long they have been here.
People that have engineer in their title.
We encourage you to meet someone new by asking someone you don't know for help. You can also ask for help in #questions or #peopleops by posting 'Who can do a video call with me to help me work on the website locally /handbook/git-page-update/ ?'. If the other options don't work for you please ask your buddy.
6. Clone the source of the website and install its dependencies
If you set up SSH keys previously, in terminal execute: git clone git@gitlab.com:gitlab-com/www-gitlab-com.git to clone the website. If you prefer using https, then execute: git clone https://gitlab.com/gitlab-com/www-gitlab-com.git, but note that if you've activated 2FA on your GitLab.com account, you'll need to take some additional steps to set up personal access tokens. If you ever want to switch between SSH and https, execute git remote remove origin, followed by git remote add origin [..] where the [..] is the part that starts with git@ for SSH, or with https: for https.
Execute: cd www-gitlab-com to change to the www-gitlab-com directory.
Execute: bundle install to install all gem dependencies.
7. Prevent newlines from causing all following lines in a file to be tagged as changed
This is especially a problem for anyone running a Mac OSX operating system. The command to 'tame' git is git config --global core.autocrlf input - execute it.
You will need to install a text editor to edit the site locally. We recommend Sublime Text 3 or Atom. Use command / ctrl P to quickly open the file you need.
Refresh your browser to see your changes.
9. Test if all URL links in a page are valid
Until this is automated in CI, a quick way to see if there are any invalid links inside a page is the following.
Install the check-my-links extension in Chrome (no other browsers support unfortunately).
Open the page you wish to preview (see previous step).
Click the newly installed extension in the upper right corner of Chrome.
A pop-up window will open and tell you how many links, if any, are invalid. Fix any invalid links and ideally any warnings, commit and push your changes, and test again.
All internal links (links leading to other parts of the website) should be relative.
10. Start contributing
Most pages that you might want to edit are written in markdown Kramdown. Read through our Markdown Guide to understand its syntax and create new content.
We are happy to have you join our company and to include you in our team page. Please follow the instructions and links below that will guide you through each step. There are instructions for both the web interface and locally, depending on your familiarity with git. Feel free to ask anyone at the company questions along the way.
Add on GitLab.com (Web IDE)
You should have received an invitation to the www-gitLab-com project at your GitLab email account. After creating your account, take note of your username and password, because you will need them throughout these steps.
Find the picture that you'd like to add to our team page, change the picture's name to the following format: yournameinlowercase.jpg or yournameinlowercase.png. (There should be no space between first and last names e.g. firstlast.jpg or firstlast.png) Ensure the picture size is around 400x400 (it must be square) and the format is JPEG or PNG. You can resize your picture using a photo editor like GIMP (cross-platform) or online by searching for "image resize". Any picture that you provide will be made black-and-white automatically after you add it to the team page.
On the project page, you will see a Web IDE button near the middle of the page next to History and Find File buttons.
In the file browser, navigate to source/images/team.
Click the + icon next to the team directory and choose upload file and choose the photo you prepared in step 2.
Next, navigate to in the file browser data/team.yml and click on it to open the editor.
Your information should already be added towards the bottom of this file. You can use CMD + F to search the page for your name or initials if you are new. If it’s not, copy the last employee’s markdown text and paste it immediately after their bio to create a new bio.
Update the initials to be your Firstname 'Nickname' Lastname. Verify that your title is entered correctly.
Add the filename of the picture that you uploaded previously, and be sure to remove the "../" before the name of the file.
Enter your Twitter and GitLab handle (without starting with an @) and write a story about yourself. Don't forget you can use other team members' information as a reference and to respect the spaces between lines. Please don't use "tab" because it will break the page format.
Once you have finished this, click the Commit button in the bottom left. It should say something like 2 unstaged and 0 staged changes. This will bring up a sidebar with an Unstaged and Staged area.
Check the file to ensure your updates are what you expect. If they are, click the check mark next to the filename to "stage" these changes.
Once you have verified all of the edits, click commit once more. Here, enter a short commit message including what you've changed. Choose Create a new branch and merge request. Choose a branch name of your choosing, usually in the format of <initials>-team-page or similar.
Fill out the merge request details and assign it to People Ops for review (the recommended assignee would be the Talent Operations Specialist who helped you with onboarding).
Add on GitLab.com (web interface)
You should have received an invitation to the www-gitLab-com project at your GitLab email account. After creating your account, take note of your username and password, because you will need them throughout these steps.
Find the picture that you'd like to add to our team page, change the picture's name to the following format: yournameinlowercase.jpg or yournameinlowercase.png. (There should be no space between first and last names e.g. firstlast.jpg or firstlast.png) Ensure the picture size is around 400x400 (it must be square) and the format is JPEG or PNG. You can resize your picture using a photo editor like GIMP (cross-platform) or online by searching for "image resize". Any picture that you provide will be made black-and-white automatically after you add it to the team page.
In GitLab.com, select the GitLab.com/www-gitlab-com project.
Click on "Files" (under "Repository" on the left-hand side menu).
Select Source, Images, then Team.
At the top of the page select “+” and upload the file. Note that your team page picture should be added to www-gitlab-com/source/images/team/NAME-OF-PERSON-IN-LOWERCASE.jpg.
Commit these changes with a specific commit message “add NAME to team page” and a unique branch. Remember the branch name as you will use it in the following steps.
Go back to the GitLab.com project. Find the branch dropdown menu at the top of your screen (default value is "master") and find the branch that you previously created to add your picture (they are in alphabetical order).
Information displayed on Team page is pulled from a data file. You can find it by clicking on each of the following items: Files, data/, and then team.yml.
When you are in team.yml, click on “edit” on the top right side of your screen.
Your information should already be added towards the bottom of this file. You can use cmd + F to search the page for your name or initials if you are new. If it’s not, copy the last employee’s markdown text and paste it immediately after their bio to create a new bio. Update the initials to be your Firstname 'Nickname' Lastname. Verify that your title is entered correctly. Add the filename of the picture that you uploaded previously, and be sure to remove the "../" before the name of the file. Enter your Twitter and GitLab handle (without starting with an @). Write a story about yourself. Don't forget to use other team members' information as a reference and to respect the spaces between lines. Please don't use "tab" because it will break the page format.
After you added your information, add a comment to your commit and click on “Commit Changes”.
Go to the Merge Request that you previously created with the branch that you are using. Assign it to People Ops for review (the recommended assignee would be the Talent Operations Specialist who helped you with onboarding).
Add Locally (using the terminal)
You should have received an invitation to the www-gitLab-com project at your GitLab email account. After creating your account, take note of your username and password, because you will need them throughout these steps.
Download Git, following the start using git documentation. Don't forget to add your Git username and to set your email.
Follow the steps to create and add your SSH keys. Note: in some of these steps, your shell will require you to add your GitLab.com username and password.
Create and checkout a new branch for the changes you will be making.
Find the picture that you’d like to add to our team page, change the picture's name to the following format: yournameinlowercase.jpg or yournameinlowercase.png (There should be no space between first and last names e.g. firstlast.jpg or firstlast.png) and then add it to the source/images/team/ directory. Follow the "how to add an image" steps. Ensure the picture size is around 400x400 (it must be square) and the format is JPEG or PNG. You can resize your picture using a photo editor like GIMP (cross-platform) or online by searching for "image resize". Any picture that you provide will be made black-and-white automatically after you add it to the team page.
Add the picture so it is staged for commit.
Information displayed on the Team page is pulled from data/team.yml.
Your information should already be added towards the bottom of this file. If it’s not, copy the last employee’s markdown text and paste it immediately after their bio to create a new profile. Update the initials to be your Firstname 'Nickname' Lastname. Verify that your title is entered correctly. Add the file name of the picture that you uploaded previously. Enter your twitter and GitLab handle. Write a story about yourself. Don't forget to use other team members' information as a reference and to respect the spaces between lines. Please don't use "tab" because it will break the page format.
After you added your information and saved your changes, add the file to be staged for commit.
To see your changes locally, follow the directions in README.md.
After validating your changes, commit your changes with a comment and push your branch.
Create a Merge Request in GitLab.com with the branch that you created. Assign it to People Ops for review (the recommended assignee would be the Talent Operations Specialist who helped you with onboarding).
Add your pet(s) to the Team Pets Page
Using what you learned in the steps above, consider adding your pet to the Team Pets page. You can follow these instructions for adding them via the Web IDE.
Again, find the picture that you'd like to add to the team pets page, and update the picture's name to the following format: petname.jpg or petname.png. Ensure the picture size is around 400x400 (it must be square).
On the project page, you will see a Web IDE button near the middle of the page next to History and Find File buttons.
In the file browser, navigate to source/images/team/pets.
Click the + icon next to the team directory and choose upload file and choose the photo you prepared in step 1.
Next, navigate to in the file browser data/pets.yml and click on it to open the editor.
Add your pet by following the format of the existing pets on the page (you can copy and paste their lines of code, even). Ensure that you include your pet's name, your name, and the image you uploaded in step 1.
Once you have finished this, click the Commit button in the bottom left. It should say something like 2 unstaged and 0 staged changes. This will bring up a sidebar with an Unstaged and Staged area.
Check the file to ensure your updates are what you expect. If they are, click the check mark next to the filename to "stage" these changes.
Once you have verified all of the edits, click commit once more. Here, enter a short commit message including what you've changed. Choose Create a new branch and merge request. Choose a branch name of your choosing.
Fill out the merge request details and assign it to People Ops for review (the recommended assignee would be the Talent Operations Specialist who helped you with onboarding).
12. Edit the Handbook
Locally, using the terminal
If you haven't already, follow steps 1-5 in the "Add yourself to the Team Page"'s "Add Locally (using the terminal)" section above. (This step is necessary as the handbook lives in the same repository as the rest of GitLab.com). If you're following this guide in order and have already added yourself to the team page, instead go back to the main branch (via git checkout master) and there create a new branch for your handbook edits.
The handbook lives under source/handbook. For the most part, you can locate the specific item to edit via that item's URL. For instance, this page is /handbook/git-page-update/ and its source lives in source/handbook/git-page-update/index.html.md.
Edit away! See the "Start Contributing" section, above, for details about the Markdown that most pages are written in.
Preview your changes locally by following the directions in README.md. Keep in mind that the local server won't auto-reload when you change a page, so you'll need to restart it to see what you've done.
Once you've made your changes and verified they appear the way you want them to, commit them with a comment and push your branch.
GitLab has a lot of places you can put web content including the website, blog, docs, and the handbook. Here's an overview of where you should create a merge request to add content.
blog: The blog is a great place to start. If you don't know where to put content, then write a blog post! Great blogs can always be then copied or modified for the website, docs, and handbook later. Blog posts are especially good for news, annoucements, and current trends because blog posts are tied to a specific date.
website: This is the main marketing site for GitLab and where folks will tend to go first to find out information about GitLab (the product and the company). The website contains a broad set of content from product pages to customer case studies. The website is the best place for evergreen articles such as topic and solution pages since it's not tied to specific date.
docs: The docs are where are all technical information about GitLab self-managed and GitLab.com belongs. If the intended audience for the content is a user of GitLab then it should be in the docs. The docs are great place for both refernce docs (what are the configurable settings for a feature, e.g. what can you do with issues) and narrative docs (how to do x with y, e.g. how to set up HA on AWS).
handbook: The handbook is for any content that needs to be used by GitLabbers to do thier job. If you put content on the blog, website, and docs, but you think it would be helpful for GitLabbers to do thier job then link to the content from the handbook.
Sometimes the lines are blurry and it can seem as though there are multiple places that would be a good fit. For example, "how to" articles make great blog posts, but could be more discoverable to users if they are in the docs. Just pick one. It's better to create content somehwere than nowhere. When in doubt, start with the blog.
