GitLab 문서의 리다이렉트

페이지를 이동, 이름 변경 또는 삭제할 때는 리다이렉트를 추가해야 합니다.
리다이렉트는 사용자가 구식 링크에서 문서 사이트를 방문할 때 404 오류를 받는 횟수를 줄여줍니다.

리다이렉트를 추가하여 다음을 보장하세요:

  • 사용자가 새 페이지를 보고 즐겨찾기를 업데이트하거나 삭제할 수 있습니다.

  • 외부 사이트가 링크를 업데이트할 수 있습니다, 특히 리다이렉트된 링크를 확인하는 자동화가 있는 사이트들입니다.

  • 문서 사이트의 전역 탐색이 누락된 페이지에 링크되지 않습니다.

    전역 탐색의 링크는 이미 gitlab-docs 프로젝트에서 테스트되었습니다.
    리다이렉트가 누락되면 gitlab-docs 프로젝트의 main 브랜치가 깨질 수 있습니다.

페이지를 이동, 이름 변경 또는 삭제하는 모든 병합 요청에 기술 작가를 지정해야 합니다.
기술 작가는 질문을 도와주고, 변경 사항을 검토할 수 있습니다.

참고:
페이지의 파일 이름을 변경하면 Google Analytics가 콘텐츠 감사에서 제거되고
페이지 조회 수가 초기화됩니다.
파일 이름을 변경하려면 먼저 페이지를 편집하여 새 페이지 이름이 가능한 한 정확한지 확인하세요.

리다이렉트의 유형

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

  • 문서 파일 자체에 추가된 리다이렉트,
    self-managed 인스턴스의 /help에서 문서를 보는 사용자를 위한 것입니다.
    예를 들어, /help on GitLab.com.
    이러한 리다이렉트는 문서의 이름을 변경하거나 이동하는 동일한 MR에 추가되어야 합니다.
    내부 페이지로의 리다이렉트는 3개월 후에 만료되고,
    외부 페이지(시작이 https:인)로의 리다이렉트는 1년 후에 만료됩니다.

  • GitLab Pages 리다이렉트,
    만료된 리다이렉트 파일 후에 자동으로 추가됩니다.
    기여자가 수동으로 추가해서는 안 되며, 9개월 후에 만료됩니다.
    외부 사이트를 가리키는 리다이렉트는 GitLab Pages 리다이렉트에 추가되지 않습니다.

만료된 리다이렉트 파일은 문서 프로젝트에서
clean_redirects Rake 작업에 의해 제거됩니다.
이는 기술 작가 팀의 월간 작업의 일환입니다.

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

페이지를 같은 저장소의 다른 페이지로 리다이렉트하려면:

  1. 새 위치로 리다이렉트할 Markdown 파일에서:

    • 모든 콘텐츠를 삭제합니다.

    • 다음 콘텐츠를 추가합니다:

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

<!-- markdownlint-disable -->

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

<!-- 이 리다이렉트 파일은 <YYYY-MM-DD> 이후에 삭제할 수 있습니다. -->
<!-- 동일한 프로젝트의 다른 문서로 가리키는 리다이렉트는 3개월 후에 만료됩니다. -->
<!-- 다른 프로젝트나 사이트의 문서를 가리키는 리다이렉트(예: 링크가 상대적이지 않고 `https:`로 시작)는 1년 후에 만료됩니다. -->
<!-- 삭제 전에 참조하십시오: 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. 이전 파일에 리다이렉트 코드를 추가하고 기존 페이지로 리다이렉트 주제의 나머지 단계를 따릅니다.

리다이렉트를 추가하는 코드 사용

스크립트를 사용하여 리다이렉트를 생성하는 것을 선호하는 경우:

다음 Rake 작업을 실행하여 이전 문서 파일에 리다이렉트 코드를 추가합니다. 첫 번째 인수는 이전 파일의 경로이고, 두 번째 인수는 새 파일의 경로입니다:

  • 같은 프로젝트의 페이지로 리다이렉트하려면 상대 경로와 .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일에 릴리즈에 추가하기 전에 이름을 변경하는 경우:

위 절차를 따르는 것 대신, 기술 작가에게 redirects.yaml에 수동으로 리다이렉트를 추가해 달라고 요청하세요.

리다이렉트를 생성하는 예외

경우에 따라 리다이렉트를 추가하는 것을 건너뛰고 파일을 삭제할 수 있습니다. 페이지는 내비게이션에서 이미 제거되었거나(또는 존재한 적이 없어야 하며), 다음 중 하나가 참이어야 합니다:

  • 페이지가 동일한 릴리즈에서 추가되고 제거되어, 자체 관리 릴리즈에 포함된 적이 없습니다.

  • 페이지에 가치 있는 내용이 포함되어 있지 않으며, 자리 표시자 페이지나 사용 통계가 극히 낮은 페이지와 같은 내용입니다.