Contractor: Update links to the new docs site across all projects and files

Issue

Now that we have rolled out the docs site, we can update links as we find them to the new format, which:

• Does not use /ee
• Uses / instead of .html
• Uses / instead of index.html

This is low priority work, as there are redirects in place to handle these old links. But if something happens to the redirects, all these links will break. It's also just nice to keep everything up to date.

Format

As per the changes above, updated links should look like this:

Before	After	Change
https://docs.gitlab.com/ee/ci/yaml/	https://docs.gitlab.com/ci/yaml/	Drop /ee
https://docs.gitlab.com/ee/ci/yaml/index.html	https://docs.gitlab.com/ci/yaml/	Drop /ee and index.html
https://docs.gitlab.com/ee/ci/yaml/lint.html	https://docs.gitlab.com/ci/yaml/lint/	Drop /ee and change lint.html to lint/

Implementation

Create MRs that update batches of links, but try to keep the MR sizes manageable. Making 3k changes in one go is not something we should do. Instead try to keep it around 10-20 links updated (OK to stretch the size a bit if needed to complete a directory, for example). Video tutorial on splitting up MRs that are too large to review.

To update the links:

1. Find and update links. Try not to update more than 10-20 at a time. Methods to do this:

   • Manual find and replace: Search for links that start with https://docs.gitlab.com/ee and manually update them to the new location. You can try each link in a browser to auto-redirect to the correct destination, if the link is still valid. For example, click on https://docs.gitlab.com/ci/index.html to see the URL change to https://docs.gitlab.com/ci/

   • Sarah's go snippet: https://gitlab.com/-/snippets/4808605

   • For VS Code users:

     Marcel's VS Code find and replace regex:

     1. Add a directory to focus on in files to include text box. For example: ./projects/gdk/gitlab/data/whats_new
     2. Enable regex in search: Select .* to right of search box.
     3. Find files with .html. In search fields:
        • Find: (https://docs.gitlab.com/)ee/(.*?)(/index)?.html
        • Replace: $1$2/
     4. Find all other files with /ee
        • Find: (https://docs.gitlab.com/)ee/
        • Replace: $1

     On the right of files and directories after you do a search, you'll see a number for the number of lines that would be changed. Hover over this to find the "replace" button. You can do individual lines, files, or whole directories. Example:

     VS Code screenshot

     

2. Optional (but very nice to have). Validate the links are still valid. Some pages or sections may have been moved or renamed, so it's good to find the new locations, but not a strict requirement.

3. Create the MR:

   • Somewhere in the description, add a link that says: Related to https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/issues/271
   • In a comment, directly @ message @marcel.amirault to make sure he sees the MR and can start the review process in a timely manner.

Projects

• gitlab-org/gitlab: ~3500+ links 😓
• gitlab-org/gitlab-runner: ~80 links gitlab-org/gitlab-runner!5448 (merged)
• gitlab-org/omnibus-gitlab: ~174 links gitlab-org/omnibus-gitlab!8236 (closed)
• gitlab-org/charts-gitlab: ~106 links
• gitlab-org/cloud-native/gitlab-operator: gitlab-org/cloud-native/gitlab-operator!1104 (merged)
• gitlab-com/www-gitlab-com: ~8000 links 😓
• gitlab-com/content-sites/handbook/: ~3200 links 😓
• gitlab-org/customers-gitlab-com/
• gitlab-org/terraform-provider-gitlab
• gitlab-org/gitaly: gitlab-org/gitaly!7659 (merged)

Additionally, likely some links in various "side" projects: https://docs.gitlab.com/development/documentation/testing/#supported-projects