GitLab /도움말
모든 GitLab 인스턴스에는 인스턴스 버전과 일치하는 /도움말(https://gitlab.example.com/도움말)이 포함되어 있습니다. 예를 들어, https://gitlab.com/도움말.
온라인으로 이용 가능한 문서는 기본 브랜치에서 매 시간 GitLab, Omnibus, Runner, Charts, Operator의 내용을 배포합니다. 문서를 업데이트하는 병합 요청이 병합된 후, 1시간 이내로 온라인에서 이용할 수 있습니다.
그러나 다음 릴리스 버전에서만 자체 관리 인스턴스의 /도움말에서 이용할 수 있습니다. 업데이트가 병합된 날짜는 해당 자체 관리 릴리스에 업데이트가 포함될 수 있는 영향을 미칩니다.
예를 들어:
-
gitlab에서 병합 요청이 문서를 업데이트합니다. 예상 릴리스 날짜가 2021-10-22인 14.4 버전의 마일스톤이 있습니다. - 2021-10-19에 병합되어 동일한 날에 온라인에서 이용할 수 있습니다. https://docs.gitlab.com.
- 2021-10-22에 GitLab 14.4가 2021-10-18의
gitlab코드 기반으로 출시되었습니다 (업데이트가 병합된 날짜의 하루 이전). - 14.4의 릴리스 기한을 놓친 경우, 해당 변경 사항은 14.5 자체 관리 릴리스에 표시됩니다.
문서 업데이트가 그 달의 릴리스에 포함되어야 하는 경우, 가능한 빨리 병합하세요.
페이지 매핑
/도움말로의 요청은 리다이렉트될 수 있습니다. 리다이렉션을 끌 경우, /도움말로의 요청이 doc 디렉토리의 특정 파일로 매핑됩니다. 예를 들어:
- 요청된 URL:
<gdk_instance>/도움말/topics/plan_and_track.md,<gdk_instance>/도움말/topics/plan_and_track.html및<gdk_instance>/도움말/topics/plan_and_track. - 매핑:
doc/topics/plan_and_track.md.
_index.md 파일
_index.md파일 지원은 GitLab 16.10에서 도입되었습니다.
Hugo 정적 사이트 생성기는 _index.md 파일을 사용합니다. /도움말에서 index.md, index.html, 또는 index로 요청될 경우, GitLab은 다음과 같이 처리합니다:
- 요청된 URL:
<gdk_instance>/도움말/user/index.md,<gdk_instance>/도움말/user/index.html, 그리고<gdk_instance>/도움말/user/index. - 매핑:
- 요청된 위치에
index.md파일이 있으면 해당 파일로. - 그렇지 않으면
_index.md파일로.
- 요청된 위치에
소스 파일
/도움말은 YAML 프론트 매터에서 title을 사용하여 레벨 1 제목을 지정할 수 있습니다. 예를 들어, title: 나의 마크다운 파일.
GitLab 16.10에서 도입되었습니다.
마크다운 자체에서도 레벨 1 제목을 지정할 수 있습니다. 예를 들어, # 나의 마크다운 파일.
두 가지 방법으로 페이지의 레벨 1 제목을 동시에 지정하지 마십시오. 그렇지 않으면 레벨 1 제목이 반복됩니다.
/도움말 링크
새로운 기능을 작성할 때 GitLab 애플리케이션에서 문서에 링크해야 할 수 있습니다. 일반적으로 app/views/ 디렉토리 내의 파일에서 help_page_path 도우미 메서드를 사용하여 이 작업이 수행됩니다.
help_page_path는 다음 규칙을 따릅니다:
- GitLab 리포지토리의
doc/디렉토리를 기준으로 상대적입니다. -
.md확장자는 생략됩니다. - 슬래시(
/)로 끝나지 않습니다.
도움말 텍스트는 Pajamas 가이드라인을 따릅니다.
HAML에서 /도움말에 링크
맥락에 따라 다음 특수 케이스를 사용하고 모든 링크 텍스트가 _() 내에 있어야 번역할 수 있도록 합니다:
-
문서 페이지에 링크하는 경우,
/도움말페이지로 링크를 생성하는 기본적인 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(../../install/relative_url.md)에 설치된 인스턴스에서도 도우미가 동작하므로 정적 경로보다 이를 선호합니다.
Ruby에서 /help 링크 걸기
Ruby 코드 내부에서 문서에 링크하려면 다음 코드 블록을 사용하여 모든 링크 텍스트가 _() 안에 있음을 확인하세요.
docs_link = link_to _('Learn more.'), help_page_url('user/permissions', 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', 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 테스트
여러 RSpec 테스트가 실행되어 GitLab 문서가 올바르게 렌더링되고 작동하는지 확인합니다. 특히, /help에서 메인 문서 랜딩 페이지가 정상적으로 작동하는지 확인합니다. 예를 들어, GitLab.com의 /help.
도움말