InfoGrab DocsInfoGrab Docs

GitLab 문서의 리디렉션

요약

페이지를 이동, 이름 변경, 또는 삭제할 때는 반드시 리디렉션을 추가해야 합니다. 다음을 보장하기 위해 리디렉션을 추가하세요: 사용자가 새 페이지를 확인하고 북마크를 업데이트하거나 삭제할 수 있습니다. 외부 사이트, 특히 리디렉션된 링크를 확인하는 자동화 기능이 있는 사이트가 링크를 업데이트할 수 있습니다.

페이지를 이동, 이름 변경, 또는 삭제할 때는 반드시 리디렉션을 추가해야 합니다. 리디렉션은 사용자가 오래된 링크를 통해 문서 사이트를 방문할 때 404 오류가 발생하는 횟수를 줄여줍니다.

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

  • 사용자가 새 페이지를 확인하고 북마크를 업데이트하거나 삭제할 수 있습니다.

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

  • 번역된 문서가 항상 영어 콘텐츠의 기존 파일로 폴백(fallback)될 수 있습니다.

  • AI 크롤러가 해당 주제의 관련 컨텍스트를 계속 찾을 수 있습니다.

  • 문서 사이트의 전역 내비게이션이 없어진 페이지로 연결되지 않습니다.

전역 내비게이션의 링크는 이미 docs-gitlab-com 프로젝트에서 테스트됩니다.

페이지를 이동, 이름 변경, 삭제하는 머지 리퀘스트에는 반드시 기술 작가(Technical Writer)를 지정하세요. 기술 작가는 질문에 답하고 변경 사항을 검토할 수 있습니다.

다른 리디렉션으로 리디렉션하지 마세요.

페이지의 파일명을 변경하면 콘텐츠 감사에서 Google Analytics 데이터가 제거되고 페이지 조회수가 처음부터 다시 시작됩니다. 파일명을 변경하려면 먼저 페이지를 편집하여 새 페이지 이름이 최대한 정확한지 확인하세요.

리디렉션 유형#

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

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

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

만료된 리디렉션 파일은 기술 작성팀의 월별 작업의 일환으로 문서 프로젝트에서 제거됩니다.

이미 존재하는 페이지로 리디렉션하기#

같은 리포지터리의 다른 페이지로 페이지를 리디렉션하려면:

  • 새 위치로 리디렉션하려는 Markdown 파일에서:

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

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

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

<!-- markdownlint-disable -->

This document was moved to [another location](../newpath/to/file/_index.md).

<!-- This redirect file can be deleted after . -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/development/documentation/redirects -->

  • ../newpath/to/file/index.md의 두 인스턴스 모두를 새 파일 경로로 교체합니다.

  • YYYY-MM-DD의 두 인스턴스 모두를 템플릿에 설명된 대로 만료 날짜로 교체합니다.

  • 페이지에 다른 페이지에서 사용되지 않는 이미지가 있으면 삭제합니다.

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

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

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

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

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

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

파일 위치 이동#

파일을 한 위치에서 다른 위치로 이동하려면, 파일을 실제로 이동하지 않습니다. 대신 파일을 복제하고 이전 파일에 리디렉션 코드를 추가합니다.

  • 새 파일을 만듭니다.

  • 이전 파일의 내용을 새 파일에 복사합니다.

  • 이전 파일에서 모든 콘텐츠를 삭제합니다.

  • 이전 파일에 리디렉션 코드를 추가하고 이미 존재하는 페이지로 리디렉션하기 항목의 나머지 단계를 따릅니다.

코드를 사용하여 리디렉션 추가#

스크립트를 사용하여 리디렉션을 만들려면:

다음 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

리디렉션 생성의 예외 사항#

일부 경우에는 리디렉션 추가를 건너뛰고 파일을 삭제하기만 해도 됩니다. 페이지가 이미 내비게이션에서 제거되었거나(또는 존재한 적이 없어야 하며), 다음 중 하나가 해당되어야 합니다:

  • 페이지가 동일한 릴리즈에서 추가되고 제거되어 GitLab Self-Managed 릴리즈에 포함된 적이 없는 경우.

  • 페이지에 유용한 콘텐츠가 없는 경우, 예를 들어 플레이스홀더 페이지이거나 사용 통계가 매우 낮은 페이지인 경우.

문제 해결#

이 섹션에는 문서 리디렉션에서 발생할 수 있는 문제에 대한 해결책이 포함되어 있습니다.

오류: 페이지 이동 후 중복 콘텐츠 경로#

파일을 같은 이름의 디렉터리로 이동하면 Hugo에서 Duplicate content path 오류가 발생할 수 있습니다. 예시:

  • 소스 파일: doc/development/testing.md (새 리디렉션이 됨)

  • 타깃 파일: doc/development/testing/_index.md

WARN  Duplicate content path: "/development/testing" file: "gitlab/doc/development/testing.md"
panic: Duplicate content path: "/development/testing" file: "gitlab/doc/development/testing.md"

이 오류는 리디렉션 파일과 새 파일 모두 동일한 URL 경로에 게시해야 하기 때문에 발생합니다. 이 예시에서 두 파일 모두 https://docs.gitlab.com/testing/에 게시되어야 하는데, 이는 유효하지 않습니다.

이 문제를 방지하려면 소스 페이지의 콘텐츠를 검토하고 새 파일이나 디렉터리에 대한 대체 이름을 선택하세요. 다른 디렉터리 이름을 선택하면 파일명으로 _index.md를 사용할 수 있습니다. 예시:

  • 소스 파일: doc/development/testing.md (새 리디렉션이 됨)

  • 타깃 파일: doc/development/backend_testing/_index.md

오류: 페이지 이동 후 File is invalidly renamed!#

이 오류는 Duplicate content path Hugo 오류와 같은 이유로 CI/CD 파이프라인에서 발생할 수 있습니다. 이 오류의 해결 방법은 Hugo 오류의 경우와 동일합니다.

GitLab 문서의 리디렉션

GitLab v19.1
원문 보기
요약

페이지를 이동, 이름 변경, 또는 삭제할 때는 반드시 리디렉션을 추가해야 합니다. 다음을 보장하기 위해 리디렉션을 추가하세요: 사용자가 새 페이지를 확인하고 북마크를 업데이트하거나 삭제할 수 있습니다. 외부 사이트, 특히 리디렉션된 링크를 확인하는 자동화 기능이 있는 사이트가 링크를 업데이트할 수 있습니다.

페이지를 이동, 이름 변경, 또는 삭제할 때는 반드시 리디렉션을 추가해야 합니다. 리디렉션은 사용자가 오래된 링크를 통해 문서 사이트를 방문할 때 404 오류가 발생하는 횟수를 줄여줍니다.

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

  • 사용자가 새 페이지를 확인하고 북마크를 업데이트하거나 삭제할 수 있습니다.

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

  • 번역된 문서가 항상 영어 콘텐츠의 기존 파일로 폴백(fallback)될 수 있습니다.

  • AI 크롤러가 해당 주제의 관련 컨텍스트를 계속 찾을 수 있습니다.

  • 문서 사이트의 전역 내비게이션이 없어진 페이지로 연결되지 않습니다.

전역 내비게이션의 링크는 이미 docs-gitlab-com 프로젝트에서 테스트됩니다.

페이지를 이동, 이름 변경, 삭제하는 머지 리퀘스트에는 반드시 기술 작가(Technical Writer)를 지정하세요. 기술 작가는 질문에 답하고 변경 사항을 검토할 수 있습니다.

다른 리디렉션으로 리디렉션하지 마세요.

페이지의 파일명을 변경하면 콘텐츠 감사에서 Google Analytics 데이터가 제거되고 페이지 조회수가 처음부터 다시 시작됩니다. 파일명을 변경하려면 먼저 페이지를 편집하여 새 페이지 이름이 최대한 정확한지 확인하세요.

리디렉션 유형#

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

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

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

만료된 리디렉션 파일은 기술 작성팀의 월별 작업의 일환으로 문서 프로젝트에서 제거됩니다.

이미 존재하는 페이지로 리디렉션하기#

같은 리포지터리의 다른 페이지로 페이지를 리디렉션하려면:

  • 새 위치로 리디렉션하려는 Markdown 파일에서:

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

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

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

<!-- markdownlint-disable -->

This document was moved to [another location](../newpath/to/file/_index.md).

<!-- This redirect file can be deleted after . -->
<!-- Redirects that point to other docs in the same project expire in three months. -->
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
<!-- Before deletion, see: https://docs.gitlab.com/development/documentation/redirects -->

  • ../newpath/to/file/index.md의 두 인스턴스 모두를 새 파일 경로로 교체합니다.

  • YYYY-MM-DD의 두 인스턴스 모두를 템플릿에 설명된 대로 만료 날짜로 교체합니다.

  • 페이지에 다른 페이지에서 사용되지 않는 이미지가 있으면 삭제합니다.

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

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

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

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

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

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

파일 위치 이동#

파일을 한 위치에서 다른 위치로 이동하려면, 파일을 실제로 이동하지 않습니다. 대신 파일을 복제하고 이전 파일에 리디렉션 코드를 추가합니다.

  • 새 파일을 만듭니다.

  • 이전 파일의 내용을 새 파일에 복사합니다.

  • 이전 파일에서 모든 콘텐츠를 삭제합니다.

  • 이전 파일에 리디렉션 코드를 추가하고 이미 존재하는 페이지로 리디렉션하기 항목의 나머지 단계를 따릅니다.

코드를 사용하여 리디렉션 추가#

스크립트를 사용하여 리디렉션을 만들려면:

다음 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

리디렉션 생성의 예외 사항#

일부 경우에는 리디렉션 추가를 건너뛰고 파일을 삭제하기만 해도 됩니다. 페이지가 이미 내비게이션에서 제거되었거나(또는 존재한 적이 없어야 하며), 다음 중 하나가 해당되어야 합니다:

  • 페이지가 동일한 릴리즈에서 추가되고 제거되어 GitLab Self-Managed 릴리즈에 포함된 적이 없는 경우.

  • 페이지에 유용한 콘텐츠가 없는 경우, 예를 들어 플레이스홀더 페이지이거나 사용 통계가 매우 낮은 페이지인 경우.

문제 해결#

이 섹션에는 문서 리디렉션에서 발생할 수 있는 문제에 대한 해결책이 포함되어 있습니다.

오류: 페이지 이동 후 중복 콘텐츠 경로#

파일을 같은 이름의 디렉터리로 이동하면 Hugo에서 Duplicate content path 오류가 발생할 수 있습니다. 예시:

  • 소스 파일: doc/development/testing.md (새 리디렉션이 됨)

  • 타깃 파일: doc/development/testing/_index.md

WARN  Duplicate content path: "/development/testing" file: "gitlab/doc/development/testing.md"
panic: Duplicate content path: "/development/testing" file: "gitlab/doc/development/testing.md"

이 오류는 리디렉션 파일과 새 파일 모두 동일한 URL 경로에 게시해야 하기 때문에 발생합니다. 이 예시에서 두 파일 모두 https://docs.gitlab.com/testing/에 게시되어야 하는데, 이는 유효하지 않습니다.

이 문제를 방지하려면 소스 페이지의 콘텐츠를 검토하고 새 파일이나 디렉터리에 대한 대체 이름을 선택하세요. 다른 디렉터리 이름을 선택하면 파일명으로 _index.md를 사용할 수 있습니다. 예시:

  • 소스 파일: doc/development/testing.md (새 리디렉션이 됨)

  • 타깃 파일: doc/development/backend_testing/_index.md

오류: 페이지 이동 후 File is invalidly renamed!#

이 오류는 Duplicate content path Hugo 오류와 같은 이유로 CI/CD 파이프라인에서 발생할 수 있습니다. 이 오류의 해결 방법은 Hugo 오류의 경우와 동일합니다.