모든 GitLab 인스턴스는 해당 인스턴스의 버전에 맞는 문서를 /help(https://gitlab.example.com/help)에서 제공합니다. 예를 들어 https://gitlab.com/help에서 확인할 수 있습니다.

https://docs.gitlab.com에서 온라인으로 제공되는 문서는 GitLab, Omnibus, Runner, Charts, Operator의 기본 브랜치에서 매 시간 배포됩니다. 문서를 업데이트하는 머지 리퀘스트가 병합되면, 한 시간 이내에 온라인에서 확인할 수 있습니다.

그러나 GitLab Self-Managed 인스턴스의 /help에서는 다음 릴리즈 버전에서야 업데이트가 반영됩니다. 업데이트가 병합된 날짜에 따라 해당 업데이트가 어떤 GitLab Self-Managed 릴리즈에 포함되는지가 달라질 수 있습니다.

예를 들어:

• gitlab의 머지 리퀘스트가 문서를 업데이트합니다. 이 머지 리퀘스트의 마일스톤은 14.4이며, 예상 릴리즈 날짜는 2021-10-22입니다.

• 2021-10-19에 병합되어 당일 https://docs.gitlab.com에서 온라인으로 확인할 수 있습니다.

• GitLab 14.4는 2021-10-18(업데이트가 병합되기 하루 전)의 gitlab 코드베이스를 기준으로 2021-10-22에 릴리즈됩니다.

• 14.4의 릴리즈 컷오프를 놓쳤기 때문에, 해당 변경 사항은 14.5 GitLab Self-Managed 릴리즈에 반영됩니다.

문서 업데이트를 해당 월의 릴리즈에 포함시키는 것이 중요하다면, 가능한 한 일찍 병합하세요.

페이지 매핑#

/help에 대한 요청은 리디렉션될 수 있습니다. 리디렉션이 꺼져 있는 경우, /help는 도움말 페이지 요청을 doc 디렉터리의 특정 파일에 매핑합니다. 예를 들어:

• 요청된 URL: <gdk_instance>/help/topics/plan_and_track.md, <gdk_instance>/help/topics/plan_and_track.html 및 <gdk_instance>/help/topics/plan_and_track.

• 매핑: doc/topics/plan_and_track.md.

_index.md 파일#

히스토리

• GitLab 16.10에서 _index.md 파일 지원이 도입됨.

Hugo 정적 사이트 생성기는 _index.md 파일을 활용합니다. /help에서 인덱스 페이지 이름이 index.md이든 _index.md이든 허용하기 위해, GitLab은 index.md, index.html, 또는 index에 대한 요청을 다음과 같이 매핑합니다:

• 요청된 위치에 파일이 존재하면 index.md로 매핑합니다.

• 그렇지 않으면 _index.md로 매핑합니다.

예를 들어:

• 요청된 URL: <gdk_instance>/help/user/index.md, <gdk_instance>/help/user/index.html, 및 <gdk_instance>/help/user/index.

• 매핑:

doc/user/index.md가 존재하면 해당 파일로 매핑합니다.

• 그렇지 않으면 doc/user/_index.md로 매핑합니다.

/help에 링크하기#

새 기능을 개발할 때, GitLab 애플리케이션에서 문서로 링크를 연결해야 할 수 있습니다. 이는 보통 app/views/ 디렉터리 내의 파일에서 help_page_path 헬퍼 메서드를 사용하여 처리합니다.

help_page_path에는 링크할 문서의 경로가 포함되며, 다음 규칙을 따릅니다:

• GitLab 리포지터리의 doc/ 디렉터리를 기준으로 하는 상대 경로입니다.

• 명확성을 위해 .md 파일 확장자로 끝나야 합니다.

도움말 텍스트는 Pajamas 가이드라인을 따릅니다.

HAML에서 /help에 링크하기#

컨텍스트에 따라 다음의 특수 케이스를 사용하고, 모든 링크 텍스트가 번역 가능하도록 _()로 감싸야 합니다:

문서 페이지에 링크하기. 가장 기본적인 형태로, /help 페이지에 대한 링크를 생성하는 HAML 코드는 다음과 같습니다:

= link_to _('Learn more.'), help_page_path('user/permissions.md'), target: '_blank', rel: 'noopener noreferrer'

앵커 링크에 링크하기. help_page_path 메서드의 일부로 anchor를 사용합니다:

= link_to _('Learn more.'), help_page_path('user/permissions.md', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'

텍스트 인라인에서 링크 사용하기. 먼저 링크를 정의한 다음 사용합니다. 이 예시에서 link_start는 링크가 담긴 변수명입니다:

- link = link_to('', help_page_path('user/permissions.md'), target: '_blank', rel: 'noopener noreferrer')
%p= safe_format(_("This is a text describing the option/feature in a sentence. %{link_start}Learn more.%{link_end}"), tag_pair(link, :link_start, :link_end))

버튼 링크 사용하기. 텍스트가 나머지 페이지 레이아웃과 맥락이 맞지 않는 곳에서 유용합니다:

= render Pajamas::ButtonComponent.new(href: help_page_path('user/group/import/_index.md'), target: '_blank') do
    = _('Learn more')

JavaScript에서 /help에 링크하기#

JavaScript 또는 Vue 컴포넌트에서 문서로 링크를 연결하려면, help_page_helper.js의 helpPagePath 함수를 사용합니다:

import { helpPagePath } from '~/helpers/help_page_helper';

helpPagePath('user/permissions.md', { anchor: 'anchor-link' })
// evaluates to '/help/user/permissions#anchor-link' for GitLab.com

이는 정적 경로보다 권장되는 방법입니다. 헬퍼가 상대 URL 하위에 설치된 인스턴스에서도 올바르게 동작하기 때문입니다.

Ruby에서 /help에 링크하기#

Ruby 코드 내에서 문서로 링크를 연결하려면, 모든 링크 텍스트가 번역 가능하도록 _()로 감싸면서 다음 코드 블록을 가이드로 사용합니다:

docs_link = link_to _('Learn more.'), help_page_url('user/permissions.md', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link)

link_to와 help_page_url 메서드를 사용할 수 없는 뷰/헬퍼 외부에서 링크를 생성해야 하는 경우, 메서드를 완전히 한정된 형태로 사용하는 다음 코드 블록을 가이드로 활용합니다:

docs_link = ActionController::Base.helpers.link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/permissions.md', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
safe_format(_('This is a text describing the option/feature in a sentence. %{docs_link}'), docs_link: docs_link)

link_to 메서드를 사용하기 위해서만 include ActionView::Helpers::UrlHelper를 사용하지 마세요. 일부 기존 코드에서 이런 패턴을 볼 수 있지만 권장하지 않습니다. 자세한 내용은 이슈 340567을 참조하세요.

/help 테스트#

GitLab 문서가 올바르게 렌더링되고 동작하는지 확인하기 위해 여러 RSpec 테스트가 실행됩니다. 특히 메인 문서 랜딩 페이지가 /help에서 올바르게 동작하는지 확인합니다. 예를 들어 GitLab.com의 /help에서 확인할 수 있습니다.