GitLab 설명서의 리다이렉션

페이지를 이동, 이름 바꾸기 또는 삭제하는 경우 리다이렉션을 추가해야 합니다. 리다이렉션을 통해 사용자가 오래된 링크에서 문서 사이트를 방문할 때 404 오류를 더 적게 만들 수 있습니다.

다음을 보장하기 위해 리다이렉션을 추가하세요:

  • 사용자가 새 페이지를 볼 수 있고 북마크를 업데이트하거나 삭제할 수 있습니다.
  • 특히 리다이렉트된 링크를 확인하는 자동화 기능이 있는 사이트와 같은 외부 사이트가 링크를 업데이트할 수 있습니다.

  • 설명서 사이트의 전역 내비게이션에 누락된 페이지로 연결되지 않습니다.

    전역 내비게이션의 링크는 이미 gitlab-docs 프로젝트에서 테스트되었습니다. 리다이렉션이 누락된 경우 gitlab-docs 프로젝트의 main 브랜치가 깨질 수 있습니다.

페이지를 이동, 이름 바꾸기 또는 삭제하는 모든 병합 요청에 기술 작가를 지정해야 합니다. 기술 작가들은 모든 질문에 답변하고 변경 내용을 검토할 수 있습니다.

참고: 페이지의 파일 이름을 변경하면 Google Analytics이 콘텐츠 감사 및 페이지 조회수가 처음부터 시작됩니다. 파일 이름을 변경하려면 먼저 페이지를 편집하여 새 페이지 이름이 가능한 정확한지 확인하세요.

리다이렉션 유형

리다이렉션에는 두 가지 유형이 있습니다:

  • 사용자가 자체 관리 인스턴스의 /help에서 문서를 보는 사용자를 대상으로 문서 파일에 추가된 리다이렉션입니다. 예를 들어, /help on GitLab.com의 경우와 같은 것입니다. 이러한 리다이렉션은 문서를 이름을 바꾸거나 이동하는 MR과 동일한 MR에서 추가해야 합니다. 내부 페이지로의 리다이렉션은 세 달 후에 만료되며 (시작이 https:인) 외부 페이지로의 리다이렉션은 1년 후에 만료됩니다.
  • GitLab Pages 리다이렉션은 리다이렉션 파일이 만료된 후에 자동으로 추가됩니다. 기여자가 수동으로 추가해서는 안 되고 이 리다이렉션은 아홉 달 후에 만료됩니다. 외부 사이트를 가리키는 리다이렉션은 GitLab Pages 리다이렉션에 추가되지 않습니다.

만료된 리다이렉션 파일은 기술 작성 팀의 월간 작업의 일환으로 clean_redirects Rake 작업에 의해 설명서 프로젝트에서 제거됩니다.

이미 존재하는 페이지로의 리다이렉션

한 리포지토리에서 다른 페이지로 리다이렉트하려면 다음을 수행하세요:

  1. 새 위치로 이동하려는 마크다운 파일:

    • 모든 내용을 삭제하세요.

    • 다음 내용을 추가하세요: 

      ---
redirect_to: '../newpath/to/file/index.md'
remove_date: 'YYYY-MM-DD'
---

<!-- markdownlint-disable -->

본 문서는 [다른 위치](../newpath/to/file/index.md)로 이동되었습니다.

<!-- 이 리다이렉션 파일은 <YYYY-MM-DD> 이후로 삭제할 수 있습니다. -->
<!-- 다른 프로젝트의 문서를 가리키는 리다이렉션은 세 달 후에 만료되며, -->
<!-- (예: 링크가 상대적이지 않고 `https:`로 시작하는 경우) 외부 문서를 가리키는 리다이렉션은 일년 후에 만료됩니다. -->
<!-- 삭제하기 전에 확인하세요: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
    • ../newpath/to/file/index.md를 새 파일 경로로 두 인스턴스 모두 바꿉니다.
    • 템플릿에서 설명된 대로 YYYY-MM-DD 만료 날짜로 두 인스턴스 모두 바꿉니다.

  2. 해당 페이지가 다른 페이지에서 사용되지 않는 이미지를 포함했다면 삭제하세요.

다른 리포지토리의 링크 업데이트

변경사항이 커밋된 후에는 이전 파일에 링크를 걸수 있는 다른 모든 리포지토리를 검색하고 업데이트하세요:

  1. https://gitlab.com/gitlab-com/www-gitlab-com에서 다음과 같이 전체 URL을 검색하세요: 

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

  2. https://gitlab.com/gitlab-org/gitlab-docs/-/tree/main/content/_data에서 .html로 끝나는 경로를 검색하세요: 

    grep -r "path/to/file.html" .

  3. 모든 설명서 프로젝트에서 문서와 코드베이스의 링크를 검색하세요. 전체 URL 및 경로만 포함한 링크를 모두 포함하여 모든 변형을 검색하세요. 예: gitlab 프로젝트의 루트 디렉터리로 이동하여 다음을 실행하세요: 

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

    모든 경우를 찾으려면 ../path/to/file 또는 ../file과 같은 상대적인 링크의 변형을 시도해야 할 수 있습니다.

  4. https://gitlab.com/gitlab-org/customers-gitlab-com에서 다음과 같이 전체 URL을 검색하세요: 

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

파일의 위치를 이동

파일을 한 위치에서 다른 위치로 이동하려면 그대로 두지 말고 파일을 복제하고 이전 파일에 리다이렉션 코드를 추가하세요.

  1. 새 파일을 생성하세요.
  2. 기존 파일 내용을 새 파일로 복사하세요.
  3. 기존 파일에서 모든 내용을 삭제하세요.
  4. 기존 파일에 리다이렉션 코드를 추가하고 이미 존재하는 페이지로의 리다이렉션 주제의 나머지 단계를 따르세요.

리다이렉션을 추가하기 위해 코드 사용

리다이렉션을 생성하기 위해 스크립트 사용을 선호하는 경우 다음을 실행하여 리다이렉션 코드를 이전 문서 파일에 추가하세요. 첫 번째 인수는 이전 파일의 경로이고 두 번째 인수는 새 파일의 경로입니다:

  • 동일한 프로젝트의 페이지로 리다이렉트하려면 상대적인 경로와 .md 확장자를 사용하세요. 이전 및 새 경로는 같은 위치에서 시작합니다. 다음 예제에서 두 경로는 모두 doc/에서 상대적입니다: 

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

  • 다른 프로젝트 또는 사이트의 페이지로 리다이렉트하려면 전체 URL(https://가 포함된)을 사용하세요: 

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

  • 또는 인수를 생략하고 값을 입력하도록 하려면 다음을 실행하세요: 

    bundle exec rake gitlab:docs:redirect

릴리스 전에 만든 페이지를 리디렉션하기

18일에 릴리스되기 전에 새 페이지를 만들고 이름을 바꾸는 경우:

그 절차를 따르는 대신에 Technical Writer에게 수동으로 리디렉션을 추가하도록 요청하십시오. redirects.yaml에 추가합니다.

리디렉션 생성에 대한 예외

일부 경우에는 리디렉션을 추가하는 대신 파일을 삭제할 수 있습니다. 페이지가 이미 내비게이션에서 제거되었거나(또는 처음부터 존재하지 않았어야 함) 한 경우이어야 하며, 다음 중 하나가 참이어야 합니다:

  • 페이지가 릴리스에 추가되고 동일한 릴리스에서 제거된 경우, 즉, Self-Managed 릴리스에 포함되지 않은 경우.
  • 페이지에 가치 있는 콘텐츠가 없는 경우(예: 플레이스홀더 페이지 또는 사용량 통계가 매우 낮은 페이지).