gitlab-org--gitlab-foss/doc/development/documentation/redirects.md

stage	group	info	description
none	Documentation Guidelines	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	Learn how to contribute to GitLab Documentation.

Redirects in GitLab documentation

Moving or renaming a document is the same as changing its location. Be sure to assign a technical writer to any merge request that renames or moves a page. Technical Writers can help with any questions and can review your change.

When moving or renaming a page, you must redirect browsers to the new page. This ensures users find the new page, and have the opportunity to update their bookmarks.

There are two types of redirects:

• Redirect added into the documentation files themselves, for users who view the docs in /help on self-managed instances. For example, /help on GitLab.com.
• GitLab Pages redirects, for users who view the docs on docs.gitlab.com.

The Technical Writing team manages the process to regularly update and clean up the redirects. If you're a contributor, you may add a new redirect, but you don't need to delete the old ones. This process is automatic and handled by the Technical Writing team.

To add a redirect:

1. In the repository (gitlab, gitlab-runner, omnibus-gitlab, or charts), create a new documentation file. Don't delete the old one. The easiest way is to copy it. For example:

   cp doc/user/search/old_file.md doc/api/new_file.md
   

2. Add the redirect code to the old documentation file by running the following Rake task. The first argument is the path of the old file, and the second argument is the path of the new file:

   • To redirect to a page in the same project, use relative paths and the .md extension. Both old and new paths start from the same location. In the following example, both paths are relative to doc/:

     bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]"
     

   • To redirect to a page in a different project or site, use the full URL (with https://) :

     bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]"
     

   Alternatively, you can omit the arguments and be asked to enter their values:

   bundle exec rake gitlab:docs:redirect
   

   If you don't want to use the Rake task, you can use the following template. However, the file paths must be relative to the doc or docs directory.

   Replace the value of redirect_to with the new file path and YYYY-MM-DD with the date the file should be removed.

   Redirect files that link to docs in internal documentation projects are removed after three months. Redirect files that link to external sites are removed after one year:

   ---
   redirect_to: '../newpath/to/file/index.md'
   remove_date: 'YYYY-MM-DD'
   ---
   
   This document was moved to [another location](../path/to/file/index.md).
   
   <!-- This redirect file can be deleted after <YYYY-MM-DD>. -->
   <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
   

3. If the documentation page being moved has any Disqus comments, follow the steps described in Redirections for pages with Disqus comments.

4. Open a merge request with your changes. If a documentation page you're removing includes images that aren't used with any other documentation pages, be sure to use your merge request to delete those images from the repository.

5. Assign the merge request to a technical writer for review and merge.

6. Search for links to the old documentation file. You must find and update all links that point to the old documentation file:

   • In https://gitlab.com/gitlab-com/www-gitlab-com, search for full URLs: grep -r "docs.gitlab.com/ee/path/to/file.html" .

   • In https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data, search the navigation bar configuration files for the path with .html: grep -r "path/to/file.html" .

   • In any of the four internal projects, search for links in the docs and codebase. Search for all variations, including full URL and just the path. For example, go to the root directory of the gitlab project and run:

     grep -r "docs.gitlab.com/ee/path/to/file.html" .
     grep -r "path/to/file.html" .
     grep -r "path/to/file.md" .
     grep -r "path/to/file" .
     

     You may need to try variations of relative links, such as ../path/to/file or ../file to find every case.

Redirections for pages with Disqus comments

If the documentation page being relocated already has Disqus comments, we need to preserve the Disqus thread.

Disqus uses an identifier per page, and for https://docs.gitlab.com, the page identifier is configured to be the page URL. Therefore, when we change the document location, we need to preserve the old URL as the same Disqus identifier.

To do that, add to the front matter the variable disqus_identifier, using the old URL as value. For example, let's say we moved the document available under https://docs.gitlab.com/my-old-location/README.html to a new location, https://docs.gitlab.com/my-new-location/index.html.

Into the new document front matter, we add the following information. You must include the filename in the disqus_identifier URL, even if it's index.html or README.html.

---
disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html'
---