Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Edit this website locally

  1. You are here:
  2. Edit this website locally

Introduction

This is a guide on what you'll need to install and run a local development environment on your machine so you can make edits locally. This allows you a better overview and preview when making complex changes.

Once you're set up, you will find the source files for the GitLab Marketing Website and GitLab Handbook in the www-gitlab-com repository

However, when you only need to make small or quick changes, the Web IDE may be easier or faster than the local development environment.

1. Help is available for team members

Editing the Handbook

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 or post in the #handbook Slack channel. You're more likely to have success with:

2. Start using GitLab

  1. Here's where you can find step-by-step guides on the basics of working with Git and GitLab. You'll need those later.
  2. Create your SSH Keys.
  3. For more information about using Git and GitLab see GitLab Docs.

3. The single script setup method (MacOS only)

This method involves running a single ZSH script which will complete all of the setup steps below for you.

Note: This script will only work on MacOS

Instructions

  1. If you have previously installed rvm or rbenv, you will want to first uninstall it by following the instructions here
  2. Open your terminal (cmd + space and search for 'Terminal').
  3. If you have previously used this script or another method to clone the repo, you can cd to the repo and directly run scripts/setup-macos-dev-environment.sh. Otherwise, if you've never set any of this up before…
  4. Copy /bin/zsh -c "$(curl -fsSL https://gitlab.com/gitlab-com/www-gitlab-com/-/raw/master/scripts/setup-macos-dev-environment.sh)" and paste into your terminal.
  5. Press enter to run the command

Switch from HTTPS to SSH

This script clones the www-gitlab-com repo to your local machine using SSH by default, but that could fail and fall back to HTTPS. If you have added an SSH key to your GitLab account, you should switch your local repo from HTTPS to SSH.

To switch your local repo from HTTPS to SSH, run the following in your local www-gitlab-com repo:

git remote set-url origin git@gitlab.com:gitlab-com/www-gitlab-com.git

See the GitLab SSH docs for more information.

Troubleshooting

4. Install Git

(Note: This step can be skipped if you used the 'single script setup method' above)

  1. Open a terminal.
  2. Check your Git version by executing: git --version.
  3. If Git is not installed, you should be prompted to install it. Follow this guide to installing Git and linking your account to Git.

5. Install a Ruby version manager

(Note: This step can be skipped if you used the 'single script setup method' above)

There is more than one way to install Ruby. Using a version manager can make it easier to upgrade as the required version for this project changes. It also prevents problems associated with different operating systems and their included version of Ruby.

There are three common version managers in use with this repository: asdf, rbenv, and rvm. There are ongoing conversations about which, if any, should be the default tool for the www-gitlab-com repository. If you just need to edit this website and you really don't care about all the nuance, you can get by just fine with the rbenv instructions.

Any of these three options is perfectly suitable, but you should only choose one. The next sections include installation instructions for each. For the most part, we will not include specific commands or instructions, but rather link to the official documentation for each tool. That way, our documentation won't become out of date as tools change their workflows. However, if you are having trouble following along, please reach out in the #website Slack channel, or submit an issue to this repository with questions and problems.

asdf

  1. Follow the asdf installation instructions. This will install the more general asdf software on your machine.
  2. With asdf installed on your machine, you'll need to add the asdf-ruby plugin. Refer to their install heading for the specific commands. If this is your first time installing a Ruby version manager, you shouldn't need to worry about any additional items in their documentation. The default should just work.
  3. Determine the current ruby version for this project by checking .ruby-version.
  4. Execute asdf install ruby <version-from-.ruby-version> in your terminal. Replace <version-from.ruby-version> with the number in .ruby-version, as mentioned in the previous step.

rbenv

  1. Follow the rbenv installation instructions. If using Linux, be aware of the following caveats:

    1. In some distributions you may get the following warning when running the rbenv-doctor script:

      You seem to have multiple rbenv installs in the following locations.
Please pick just one installation and remove the others.

/usr/bin/rbenv
/bin/rbenv

      This is most probably a false positive in the rbenv-doctor script. It turns out in many Linux distros (e.g. Ubuntu starting from Ubuntu 19.04, Fedora starting from Fedora 17) /bin is actually a symlink to /usr/bin. So, these would be the same installation and not different ones. This can be confirmed by running ll /bin (or ls -alF /bin if you don't have the ll alias).

    2. You may need to manually install the latest version of ruby-build as the one provided in your distribution's package repository may be outdated and not able to install the project's required ruby version. This is known to be the case at least for Pop!_OS 21.04 (based on Ubuntu 21.04).

  2. Install the project's current ruby version by typing rbenv install in your terminal. The required version should be automatically detected from the .ruby-version file. This can be confirmed by running rbenv version.

rvm

  1. Follow the rvm installation instructions
  2. Once RVM has been installed, ensure that your updated terminal environment has been loaded by closing your terminal window and opening a new one.
  3. Determine the current ruby version for this project by checking .ruby-version.

6. Clone the source of the website

(Note: This step can be skipped if you used the 'single script setup method' above)

There are two ways to clone this repository: ssh or https. You only need to choose one.

Clone via SSH

The GitLab documentation covers how to setup SSH keys. If you haven't already done this - or aren't sure - read through the GitLab SSH docs. When you have your SSH keys added to your GitLab account:

  1. In a terminal, execute: git clone git@gitlab.com:gitlab-com/www-gitlab-com.git to clone the website.

Clone via HTTPS

If you prefer using https, then:

  1. In a terminal, execute: git clone https://gitlab.com/gitlab-com/www-gitlab-com.git

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 on your GitLab.com account.

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.

7. Install and verify dependencies

  1. Execute: cd www-gitlab-com to change to the www-gitlab-com directory created when you cloned the repository.
  2. Execute: bundle install to install all gem dependencies.
  3. Execute: yarn install to install all JavaScript dependencies.
  4. Install additional dependencies Homebrew, nvm, and yarn. If not installed, step 9 may result in an error. (Note: This step can be skipped if you used the 'single script setup method' above)
  5. Each time you update this repository (git pull) new dependencies might be required. You can execute the bin/doctor script to check your ruby version, bundle, and yarn, and receive suggestions for updating these.

8. Prevent newlines from causing all following lines in a file to be tagged as changed

Git is able to automatically convert line endings between CRLF and LF and vice versa. Execute the following command to configure Git to convert CRLF to LF on commit but otherwise leave line endings alone:

git config --global core.autocrlf input

If you'd like to learn more about Git's formatting and whitespace options see the "Formatting and Whitespace" section under "Git Configuration" in "Pro Git".

9. Preview website changes locally

  1. In a terminal, execute:
    1. Change to the directory for your site, for example: cd sites/handbook (see monorepo docs for more details)
    2. NO_CONTRACTS=true bundle exec middleman
  2. Wait for the log line: == Webpack proxy server enabled: use "http://localhost:4567" or "http://127.0.0.1:4567"
  3. Visit http://localhost:4567/ in your browser
  4. You will need to install a text editor to edit the site locally. We recommend VS Code, Sublime Text 3 or Atom. Use command / ctrl + p to quickly open the file you need.
  5. Refresh your browser to see your changes

10. 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.

  1. Install the check-my-links extension in Chrome or the Broken Link Checker addon in Firefox.
  2. Open the page you wish to preview (see previous step).
  3. 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.

11. 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.

Instructions on how to update the website are in the readme of www-gitlab-com.

For more in-depth details on setting up and using the local development environment, see doc/development.md.

12. Add yourself to the Team Page

We are happy to have you join our company and to include you in our team page! A sync will add a basic entry for you on our team page on your third day of employment at GitLab. You are invited to personalize this entry and add more information to it.

Ask anyone in the company for help if you need it - you can use either the #mr-buddies or #questions Slack channel for this purpose. There are three ways to update the website.

  1. Add your info on GitLab.com using the Web IDE
  2. Add your info on GitLab.com using the 'web interface'
  3. Add your info using a Local Git clone (using the terminal and an IDE)

Choose the method below that feels most comfortable and have the following information handy:

Method 1: Add your info on GitLab.com using Web IDE

  1. Go to the Team page and find yourself. Note: if you choose No in Workday for Export Name/Location to Team Page? you will have to find yourself by your job title instead of your name.
  2. Click on the avatar above your name (or job title). A modal will open.
  3. In that modal, on the bottom, click Edit in Web IDE
  4. Our web editor will open with your team page entry opened.
  5. Once you have found the file with your name or slug in its title, in the directory data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/ (make sure you are searching within the file you want to edit by clicking on the file first), update your details:
    • Update your name if needed to your FirstName LastNameor PreferredName LastName
    • locality should be left empty
    • country should be set to Remote
    • Verify your role
    • If your position title is incorrect or not filled in, navigate to job_families.yml and use command-F (macOS) or ctrl-F (nix) to search for your job title. You can search for .yml files in the Web IDE using command-P (macOS) or ctrl-P (nix)
    • Check that your role links to your job description. If not, add a link. For example, change <a href="">Solutions Architect</a> to <a href="/job-families/sales/solutions-architect/">Solutions Architect</a>.
    • Verify reports_to lists your manager using the slug value from their team page entry
    • If you are a manager, verify the reports_to of your direct reports are referring to your slug
    • Add the filename of your profile picture, making sure to match letter case. Delete ../gitlab-logo-extra-whitespace.png, if present. The completed line should look like this: picture: yournameinlowercase.jpg.
    • Add your pronouns
    • Consider adding pronunciation for your full name to help others to pronounce your name correctly (e.g. sid see-brandy for Sid Sijbrandij)
    • Add your Twitter and GitLab handles without the leading @
    • Ensure your list of departments is accurate. Use other team members' as a reference.
    • Add your specialty
    • Add your expertise
    • Add your own story. Use other team members' stories as a reference.
    • If remote work has changed your life in a meaningful way, consider adding your own remote_story, using other team members' remote stories as a reference
    • Update any data that was filled in but is incorrect

Important: Do not use the tab character, and respect the spaces between lines to avoid breaking the page format. Referenced file names/extensions are case sensitive, and a file that is not found will cause a pipeline failure. The file should end with an empty newline or it will cause a pipeline failure.

  1. To upload your image, ensure that it is prepared according to the Picture Requirements.
  2. Navigate to find the team folder using the path sites/uncategorized/source/images/team/. To do this, you must first notice that you are in a file that is within the person folder, which is within the team_members folder, which is within the data folder. You can close folders by clickin on the V to the left of the folder name. Once you have closed the data folder, you will see the sites folder 6 folders down. Open sites by clicking the >, then uncategorized, then source, then images, and finally team`.
  3. Right click on team and choose Upload.
  4. Select the image you want to upload and Open.
  5. Now you will navigate back to your team page entry. You can do this by either closing the sites folder and opening data, thhen team members, person, and the folder containing you file; or you can notice your file tab on the top bar, and you can click on it to be taken to that file.
  6. Update your picture field to your filename. Delete the content that is this line after the picture: that starts with ../gitlab etc. Make sure to match the letter case of your picture file. The completed line should look like this: picture: yournameinlowercase.jpg for example.
  7. Once you have finished this, click the Source Control icon, as described in point 5 of Using the new Web IDE to edit the handbook.
  8. Create a title for your MR, and enter it in the box above the Commit & Push button. An example title would be Updating My Team Page Entry.
  9. Click the Commit & Push button.
  10. Click on Yes Commit to a new branch.
  11. You will then be in the New branch name section. Enter your branch name, in the format of yourinitials-add-YOURNAME-to-team-page-date or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06 and press Return/Enter.
  12. Click on Create MR. If this message disappears, click on the notification bell icon on the bottom right, and it will bring back the message.
  13. In the Desciption box, explain Why is this change being made? as decribed. For this specific MR, you can enter something like: Adding my information and picture to the team page due to onboarding tasks.
  14. Scroll down and Create merge request.
  15. Review the Author Checklist and check off all applicable tasks. Add your People Connect onboarding team member and Manager as Reviewers. If your manager has a gold triangle symbol with an exclamation mark on their bottom right section of their avatar photo, it means that they do not have merge rights to the team page so you can assign the MR to your People Connect team member if that is the case. If there is no triangle on your manager avatar, you may assign the MR to your manager.

Method 2: Add your info on GitLab.com using the 'web interface'

  1. Go to the GitLab.com / www-gitlab-com project.
  2. Click the + under the red line near the top of the screen.
  3. Click New branch.
  4. For Branch name, name it something unique (it's temporary so don't worry too much about the exact name) like your initials-team-page-update-yourdepartment-the date and click Create branch. Example: hk-team-page-update-custsupport-feb06
  5. Start by adding your image. Click on Repository on the left side then Files.
  6. In the file browser, navigate to sites/uncategorized/source/images/team
  7. At the top of the page click + and choose Upload file to upload your picture. Be sure to follow the picture requirements. Add text Add YourFirstName YourLastName to team page and click Upload file.
  8. Navigate on your branch near the top of the page following the text that has your unique branch name and click on the text that follows your branch name www-gitlab-com.
  9. Now you will edit your biographical information. All the bio information displayed on the Team page is pulled from a data file. Click on data, and then scroll down to team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/SLUG_REPLACE.yml (you are looking for a file that specifies your name or slug).
  10. Click on edit on the top right side of your screen.
  11. Once you have found the file with your name or slug in its title, in the directory data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/ (make sure you are searching within the file you want to edit by clicking on the file first), update your details:
    • Update your name if needed to your FirstName LastNameor PreferredName LastName
    • locality should be left empty
    • country should be set to Remote
    • Verify your role
    • If your position title is incorrect or not filled in, navigate to job_families.yml and use command-F (macOS) or ctrl-F (nix) to search for your job title. You can search for .yml files in the Web IDE using command-P (macOS) or ctrl-P (nix)
    • Check that your role links to your job description. If not, add a link. For example, change <a href="">Solutions Architect</a> to <a href="/job-families/sales/solutions-architect/">Solutions Architect</a>.
    • Verify reports_to lists your manager using the slug value from their team page entry
    • If you are a manager, verify the reports_to of your direct reports are referring to your slug
    • Add the filename of your profile picture, making sure to match letter case. Delete ../gitlab-logo-extra-whitespace.png, if present. The completed line should look like this: picture: yournameinlowercase.jpg.
    • Add your pronouns
    • Consider adding pronunciation for your full name to help others to pronounce your name correctly (e.g. sid see-brandy for Sid Sijbrandij)
    • Add your Twitter and GitLab handles without the leading @
    • Ensure your list of departments is accurate. Use other team members' as a reference.
    • Add your specialty
    • Add your expertise
    • Add your own story. Use other team members' stories as a reference.
    • If remote work has changed your life in a meaningful way, consider adding your own remote_story, using other team members' remote stories as a reference
    • Update any data that was filled in but is incorrect

Important: Do not use the tab character, and respect the spaces between lines to avoid breaking the page format. Referenced file names/extensions are case sensitive, and a file that is not found will cause a pipeline failure. The file should end with an empty newline or it will cause a pipeline failure.

  1. After you added your information, add a comment to your commit and click on “Commit Changes”.
  2. Now Create a merge request in GitLab.com with the branch that you created by clicking Create merge request button.
    • Create a title that describes your changes at a high level.
    • Add a description of your changes
    • Assign the merge request to yourself
    • Make sure the source branch is the one you created hk-team-page-update-custsupport-feb06 (as an example from above) and the target is master
    • Check the box delete source branch when merge request is accepted
  3. Click create merge request At the upper right of the new page, click edit next to Reviewer and set your manager as reviewer for this merge request.

Method 3: Add your info using a Local Git clone (using the terminal and an IDE)

Note: This method may take longer than other methods, because it requires git clone for around 4GB size repository.

  1. Download Git, following the start using git documentation.
  2. Follow the steps to create and add your SSH keys.
  3. Clone the www-gitlab-com project through your shell, following the command line commands documentation.
  4. Create and checkout a new branch for the changes you will be making.
  5. Add your picture to the sites/uncategorized/source/images/team/ directory in the repository and git add it. Be sure to follow the picture requirements.
  6. Open data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/SLUG_REPLACE.yml in your favorite editor, specifically looking for the file with your name or slug.
  7. Once you have found the file with your name or slug in its title, in the directory data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/ (make sure you are searching within the file you want to edit by clicking on the file first), update your details:
    • Update your name if needed to your FirstName LastNameor PreferredName LastName
    • locality should be left empty
    • country should be set to Remote
    • Verify your role
    • If your position title is incorrect or not filled in, navigate to job_families.yml and use command-F (macOS) or ctrl-F (nix) to search for your job title. You can search for .yml files in the Web IDE using command-P (macOS) or ctrl-P (nix)
    • Check that your role links to your job description. If not, add a link. For example, change <a href="">Solutions Architect</a> to <a href="/job-families/sales/solutions-architect/">Solutions Architect</a>.
    • Verify reports_to lists your manager using the slug value from their team page entry
    • If you are a manager, verify the reports_to of your direct reports are referring to your slug
    • Add the filename of your profile picture, making sure to match letter case. Delete ../gitlab-logo-extra-whitespace.png, if present. The completed line should look like this: picture: yournameinlowercase.jpg.
    • Add your pronouns
    • Consider adding pronunciation for your full name to help others to pronounce your name correctly (e.g. sid see-brandy for Sid Sijbrandij)
    • Add your Twitter and GitLab handles without the leading @
    • Ensure your list of departments is accurate. Use other team members' as a reference.
    • Add your specialty
    • Add your expertise
    • Add your own story. Use other team members' stories as a reference.
    • If remote work has changed your life in a meaningful way, consider adding your own remote_story, using other team members' remote stories as a reference
    • Update any data that was filled in but is incorrect

Important: Do not use the tab character, and respect the spaces between lines to avoid breaking the page format. Referenced file names/extensions are case sensitive, and a file that is not found will cause a pipeline failure. The file should end with an empty newline or it will cause a pipeline failure.

  1. Save the changes to the file in data/team_members/person/FIRST_LETTER_OF_YOUR_FIRST_NAME/ that you just edited, and git add it.
  2. To see your changes locally:
    1. Manually run a command to compile the changes you just made into a file that actually populates the team page:
      cd <WWW-GITLAB-COM REPO ROOT>
bundle exec rake build:team_yml
    2. Follow the preview directions in development.md.
  3. After validating your changes, commit your changes to the branch of www-gitlab-com that you created in step 4, with a comment Add FirstName LastName to team page and push your branch. You may need to set the remote as upstream or you can use --set-upstream option and specify remote as upstream.
  4. Create a Merge Request in GitLab.com with the branch that you created and assign your manager as reviewer.

Note: When you test locally, the map on top of the page won't show your photo. This is because it is not populated with local data. More about how the map works. You will see your picture on the map as soon as your Merge Request is merged. Note: Searching the handbook in your local environment yields production results, so navigate directly to the team page via URL to see your changes.

Add your pet(s) to the Team Pets Page

Using what you learned in the steps above, consider adding your pet(s) to the Team Pets page. You can follow these instructions to add them via the Web IDE.

  1. 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, see picture requirements).
  2. Go to the GitLab.com / www-gitlab-com project.
  3. On the Repository page, you will see a Web IDE button near the middle of the page next to the Find File button.
  4. In the browser window, navigate to sites/uncategorized/source/images/team/pets.
  5. Right click on pets and choose Upload.
  6. Select the image you want to upload and Open.
  7. Next, navigate to data/pets.yml and click on it to open the editor.
  8. Scroll to the end of the file. 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 full name, and the name of the image you uploaded in step 1.
  9. Once you have finished this, click the Source Control icon, as described in point 5 of Using the new Web IDE to edit the handbook.
  10. Create a title for your MR. An example title would be Adding my dog Gary to the Team Pets Page.
  11. Click the Commit & Push button.
  12. Click on Yes Commit to a new branch.
  13. You will then be in the New branch name section. Enter your branch name, in the format of yourinitials-add-YOURNAME-to-team-page-date or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06 and press Return/Enter.
  14. Click on Create MR. If this message disappears, click on the notification bell icon on the bottom right, and it will bring back the message.
  15. Fill out the merge request details and assign it to your manager for review.

13. Edit the Handbook

WebIDE, using the browser

The Web Integrated Development Environment (IDE) is used to make changes within the browser. This method requires no setup.

  1. Find the handbook page to edit.
  2. Click on the Open in Web IDE link on the top right section, above On this page; or click the Edit in Web IDElink at the bottom of the page.
  3. Edit the page using MarkDown. You can preview your changes (but links will not work).
    • Note: You can edit other pages by browsing through the filelist on the left side in the Web IDE.
  4. After making your changes, click the Source Control symbol on the left side (under the Search / magnifying glass symbol).
  5. Write a Commit message, which will be the title of your merge request, and click Commit & Push. The message or title should be as brief as possible, since it has a character limit. You can add more detail in the description in a subsequent step.
    1. Click on Yes Commit to a new branch.
  7. You will then be in the New branch name section. Enter your branch name, in the format of yourinitials-add-YOURNAME-to-team-page-date or similar. Example: plh-add-paulalilyherbert-to-team-page-feb06 and press Return/Enter.
  8. Click on the Create MR button on the bottom right. If this message disappears, click on the notification bell icon on the bottom right, and it will bring back the message.
  9. Submit and you will be taken to the merge request (MR) page.
  10. Feel free to add a more detailed message in the description box.
  11. Assign the MR to the Directly Responsible Individual (DRI):
    • If the DRI for the page(s) being updated isn't immediately clear, then assign it to your manager.
    • If your manager does not have merge rights, please ask someone to merge it after it has been approved by your manager in #mr-buddies.

Locally, using the terminal

  1. 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.
  2. The handbook lives under sites/handbook/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 sites/handbook/source/handbook/git-page-update/index.html.md.erb.
  3. Edit away! See the "Start Contributing" section, above, for details about the Markdown that most pages are written in.
  4. 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.
  5. 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.
  6. As above, Create a Merge Request in the www-gitlab-com project. If you're onboarding, don't forget to assign it to your manager.

Marking a merge request as draft

  1. You can easily prevent a merge request from being merged before you're ready by marking it as a work in progress. Simply type "Draft:" at the beginning of your merge request title (e.g. "Draft: My Handbook Change"). To merge once you're ready, select "Mark as ready" around the title.
  2. Note: Only mark a merge request as draft if it will negatively affect the company if merged too early. That can be the case for application code but is almost never possible for handbook MRs.

Ready to merge

Handbook Merge Requests should have the branch set to delete. It should not have commits set to squash. We do not squash commits because of the possible negative effects. Then assign the MR to a maintainer for review and merging.

Team member merge requests being labeled as Community contributions

If you recently created a Merge Request that was labeled as a Community contribution, you can fix this mislabeling issue going forward by updating the GitLab username in your personal entry in the team member directory to match the GitLab account you use for work.

Here is how you can do that:

  1. Search for your last name using Find File feature in the www-gitlab-com project OR head to https://gitlab.com/gitlab-com/www-gitlab-com/-/tree/master/data/team_members/person, open the folder that matches with the first initial of your first name, and find your file.
  2. Open your file.
  3. Once the file is open, click on the Edit button.
  4. Update the gitlab attribute (typically found on line 11) in the file so that the entry is an exact match for the GitLab.com username you use for work.
  5. Create a Merge Request and assign to your manager or ask for help in mr-buddies in Slack.

Where should content go?

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.

  1. 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, announcements, and current trends because blog posts are tied to a specific date.
  2. 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.
  3. 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 reference 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).
  4. handbook: The handbook is for any content that needs to be used by GitLab team-members to do their job. If you put content on the blog, website, and docs, but you think it would be helpful for GitLab team-members to do their 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 somewhere than nowhere. When in doubt, start with the blog.

Open in Web IDE View source