GitLab /도움말
모든 GitLab 인스턴스에는 인스턴스의 버전과 일치하는 /help
(https://gitlab.example.com/help
)에 문서가 포함되어 있습니다. 예를 들어, https://gitlab.com/help.
온라인으로 이용 가능한 문서는 기본 브랜치에서 GitLab, Omnibus, Runner, Charts 및 Operator로부터 매 시간 배포됩니다. 문서를 업데이트하는 Merge Request이 Merge된 후 1시간 이내에 온라인으로 이용할 수 있습니다.
그러나 다음 릴리스 버전에서만 Self-Managed형 인스턴스의 /help
에만 이용 가능합니다. 업데이트가 Merge된 날짜에 따라 업데이트가 포함된 Self-Managed형 릴리스가 변경될 수 있습니다.
예를 들어:
-
gitlab
의 Merge Request이 문서를 업데이트합니다. 14.4 버전의 마일스톤이 있으며, 2021-10-22에 예정된 릴리스 날짜를 가지고 있습니다. - 2021-10-19에 Merge되고, 같은 날 https://docs.gitlab.com에서 온라인으로 이용할 수 있습니다.
- 2021-10-22에 GitLab 14.4가 릴리스되며, 2021-10-18의
gitlab
코드베이스를 기반으로합니다(업데이트가 Merge된 날짜보다 하루 이전). - 14.4의 릴리스 절단 시점을 놓쳐 14.5 Self-Managed형 릴리스에 표시됩니다.
문서 업데이트가 해당 월의 릴리스에 포함되어야 하는 경우, 가능한 빨리 Merge하십시오.
페이지 매핑
/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
파일
_index.md
파일 지원은 GitLab 16.10에서 소개되었습니다.
Hugo 정적 사이트 생성기는 _index.md
파일을 활용합니다. /help
에서 index.md
또는 _index.md
의 페이지를 허용하기 위해 GitLab은 index.md
, index.html
, 또는 index
로의 요청을 다음과 같이 매핑합니다:
- 요청된 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
는 YAML 프론트 매터를 사용하여 title
로 명시된 1단계 제목이 있는 마크다운 파일을 렌더링 할 수 있습니다. 예를 들어, title
: My Markdown file
.
GitLab 16.10에서 소개되었습니다.
페이지의 1단계 제목을 동시에 두 가지 방법으로 지정해서는 안 되며, 그렇게 할 경우 1단계 제목이 중복됩니다.
/help
링크
새로운 기능을 개발할 때 GitLab 애플리케이션에서 문서에 링크를 걸어야 할 수도 있습니다. 이는 일반적으로 app/views/
디렉터리 내의 파일에서 help_page_path
도우미 메서드를 사용하여 수행됩니다.
help_page_path
는 다음 규칙을 따릅니다:
- GitLab 리포지터리의
doc/
디렉터리를 기준으로 상대적입니다. -
.md
확장자를 생략합니다. - 마지막에 슬래시(
/
)로 끝나지 않습니다.
도움말 텍스트는 파자마스 가이드라인에 따릅니다.
HAML에서 /help
에 링크 걸기
맥락에 따라 다음과 같은 특수한 경우를 사용하며, 모든 링크 텍스트는 번역 가능하도록 _()
내에 있어야 합니다:
-
문서 페이지에 링크 걸기. 가장 기본적인 형태로,
/help
페이지로의 링크를 생성하는 HAML 코드는 다음과 같습니다:= link_to _('자세히 알아보기.'), help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer'
-
앵커 링크에 링크 걸기.
help_page_path
메서드의 일부로anchor
를 사용합니다:= link_to _('자세히 알아보기.'), help_page_path('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
-
텍스트 내에 링크 사용하기. 먼저 링크를 정의한 다음 사용합니다. 이 예에서
link_start
는 링크를 포함하는 변수의 이름입니다:- link = link_to('', help_page_path('user/permissions'), target: '_blank', rel: 'noopener noreferrer') %p= safe_format(_("텍스트는 문장에서 옵션/기능을 설명하는것. %{link_start}자세히 알아보기.%{link_end}"), tag_pair(link, :link_start, :link_end))
-
버튼 링크 사용하기. 텍스트가 페이지 레이아웃과 맥락에서 벗어날 수 있는 곳에서 유용합니다:
= link_to _('자세히 알아보기.'), help_page_path('user/permissions'), class: 'btn btn-info', target: '_blank', rel: 'noopener noreferrer'
JavaScript에서 /help
에 링크 걸기
JavaScript 또는 Vue 컴포넌트에서 문서에 링크를 걸고자 하는 경우, help_page_helper.js
의 helpPagePath
함수를 사용합니다:
import { helpPagePath } from '~/helpers/help_page_helper';
helpPagePath('user/permissions', { anchor: 'anchor-link' })
// 결과: GitLab.com에서 '/help/user/permissions#anchor-link'로 평가됩니다.
이는 정적 경로보다 선호되며, 도우미가 상대적 URL에 설치된 인스턴스에서도 작동합니다.
Ruby에서 /help
에 링크 걸기
Ruby 코드 내에서 문서에 링크하기 위해 _()
내에 모든 링크 텍스트가 있도록 다음 코드 블록을 사용합니다:
docs_link = link_to _('자세히 알아보기.'), help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
safe_format(_('이것은 문장에서 옵션/기능을 설명하는 텍스트입니다. %{docs_link}'), docs_link: docs_link)
link_to
및 help_page_url
메서드가 사용할 수 없는 뷰/헬퍼 외부에서 링크를 생성해야 하는 경우, 메서드가 완전히 정규화된 위치에서 사용할 수 있도록 다음 코드 블록을 사용합니다:
docs_link = ActionController::Base.helpers.link_to _('자세히 알아보기.'), Rails.application.routes.url_helpers.help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer'
safe_format(_('이것은 문장에서 옵션/기능을 설명하는 텍스트입니다. %{docs_link}'), docs_link: docs_link)
기존의 코드에서 일부에서 볼 수 있는 것처럼 link_to
메서드를 사용할 수 있도록 하기 위해 include ActionView::Helpers::UrlHelper
를 사용하지 않도록 해야 합니다. 더 자세한 내용은 이슈 340567에서 확인하십시오.
/help
테스트
GitLab 문서가 올바르게 렌더링되고 작동하는지 확인하기 위해 여러 RSpec 테스트가 실행됩니다. 특히 /help
에서 메인 문서 랜딩 페이지가 올바르게 작동하는지 확인합니다. 예를 들어, GitLab.com의 /help
입니다.