GitLab 문서의 리다이렉트
페이지를 이동, 이름 바꾸기 또는 삭제하는 경우 리다이렉트를 추가해야 합니다. 리다이렉트를 추가하면 사용자가 오래된 링크에서 문서 사이트를 방문했을 때 404 오류를 더 적게 만납니다.
리다이렉트를 추가하여 확인하세요:
- 사용자가 새로운 페이지를 볼 수 있고, 즐겨찾기를 업데이트하거나 삭제할 수 있습니다.
- 외부 사이트가 리다이렉트된 링크를 체크하는 자동화가 있는 사이트들이 특히 링크를 업데이트할 수 있습니다.
-
문서 사이트의 글로벌 내비게이션이 없는 페이지로 연결되지 않도록 합니다.
글로벌 내비게이션의 링크는 이미 ‘gitlab-docs’ 프로젝트에서 테스트되었습니다. 리다이렉트가 누락되면, ‘gitlab-docs’ 프로젝트의 ‘main’ 브랜치가 망가질 수 있습니다.
페이지를 이동, 이름 바꿈 또는 삭제하는 Merge Request에 기술 작가(Technical Writer)를 지정하십시오. 기술 작가는 질문에 답변하고 변경 내용을 검토할 수 있습니다.
리다이렉트의 종류
리다이렉트에는 두 가지 유형이 있습니다:
-
문서 파일 자체에 추가된 리다이렉트는
Self-Managed형 인스턴스의
/help
에서 문서를 보는 사용자들을 위한 것입니다. 예를 들어,/help
on GitLab.com에 해당합니다. 이러한 리다이렉트는 문서를 이름을 변경하거나 이동시키는 동일한 Merge Request에 추가되어야 합니다. 내부 페이지로의 리다이렉트는 세 달 후에 만료되며 (https:로 시작하는) 외부 페이지로의 리다이렉트는 1년 후에 만료됩니다. - GitLab Pages 리다이렉트는 만료된 리다이렉트 파일 이후에 자동으로 추가됩니다. 기여자들이 매뉴얼으로 추가해서는 안 되며, 아홉 개월 후에 만료됩니다. 외부 사이트를 가리키는 리다이렉트는 GitLab Pages 리다이렉트에 추가되지 않습니다.
만료된 리다이렉트 파일은 기술 문서 팀의 월간 작업 일환으로 문서 프로젝트에서 제거됩니다.
이미 존재하는 페이지로의 리다이렉트
한 리포지터리에서 다른 페이지로 리다이렉트하려면:
-
새 위치로 리다이렉트하고자 하는 마크다운 파일에서 다음을 수행하세요:
- 모든 콘텐츠를 삭제합니다.
-
다음 내용을 추가합니다:
--- redirect_to: '../newpath/to/file/index.md' remove_date: 'YYYY-MM-DD' --- [다른 위치](../path/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
만료 일에 해당하는 두 경우를 모두 교체합니다.
-
변경 내용을 커밋한 후 이전 파일을 가리키는 모든 링크를 찾아 업데이트합니다:
-
https://gitlab.com/gitlab-com/www-gitlab-com에서 전체 URL을 검색합니다:
grep -r "docs.gitlab.com/ee/path/to/file.html" .
-
https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data에서 내비게이션 바 구성 파일에서
.html
경로를 검색합니다:grep -r "path/to/file.html" .
-
네 개의 내부 프로젝트 중 하나에서 문서와 코드베이스에서 링크를 검색합니다. 전체 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’과 같이 상대적인 링크의 변형을 시도해야 할 수 있습니다.
-
파일의 위치를 옮기기
파일을 한 위치에서 다른 위치로 옮기려면 파일을 옮기지 마세요. 대신 파일을 복사하고 이전 파일에 리다이렉트 코드를 추가하세요.
- 새 파일을 생성합니다.
- 이전 파일의 내용을 새 파일로 복사합니다.
- 이전 파일에서 모든 콘텐츠를 삭제합니다.
- 이전 파일에 리다이렉트 코드를 추가하고 이미 존재하는 페이지로의 리다이렉트 주제의 나머지 단계를 따릅니다.
리다이렉트를 추가하는 코드 사용
리다이렉트를 생성하는 스크립트를 사용하는 경우:
이전 문서 파일에 리다이렉트 코드를 추가하려면 다음 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
에 리다이렉트를 매뉴얼으로 추가하는 방법을 기술 작가에게 물어보세요.
리다이렉트 생성의 예외사례
일부 경우에는 리다이렉트를 추가하지 않고 파일을 삭제할 수 있습니다. 이 경우 페이지는 이미 내비게이션에서 제거되었거나 제거된 적이 없어야 하며, 다음 중 하나가 충족되어야 합니다:
- 페이지가 동일한 릴리스에서 추가되고 제거되었으므로 Self-Managed형 릴리스에 포함되지 않았습니다.
- 페이지에는 플레이스홀더 페이지나 사용량 통계가 매우 낮은 페이지와 같은 가치 없는 콘텐츠가 없습니다.