GitLab /help
모든 GitLab 인스턴스에는 인스턴스 버전과 일치하는 /help (https://gitlab.example.com/help)의 문서가 포함되어 있습니다. 예를 들어, https://gitlab.com/help입니다.
온라인으로 사용 가능한 설명서(https://docs.gitlab.com)는 GitLab, Omnibus, Runner, Charts, Operator의 기본 브랜치에서 매 시간 배포됩니다. 문서 업데이트를 통합하는 병합 요청 후, 1시간 이내로 온라인에서 사용할 수 있습니다.
그러나 다음 릴리즈 버전에서는 자체 관리 인스턴스의 /help에서만 사용할 수 있습니다. 업데이트가 통합된 날짜는 업데이트가 포함된 자체 관리 릴리즈 버전에 영향을 미칠 수 있습니다.
예를 들면:
- ‘gitlab’에서 병합 요청이 문서를 업데이트합니다. 예상 릴리스 날짜가 2021-10-22인 14.4의 마일스톤이 함께 있습니다.
- 2021-10-19에 통합되어 동일한 날에 온라인에서 사용할 수 있습니다 https://docs.gitlab.com.
- GitLab 14.4는 2021-10-18의 ‘gitlab’ 코드 기반으로 2021-10-22에 릴리스됩니다 (업데이트가 통합된 날짜의 전날).
- 14.4의 릴리스 기한을 놓치기 때문에 변경 사항은 14.4에 표시되지 않고 14.5의 자체 관리 릴리스에 나타납니다.
문서 업데이트가 해당 월의 릴리스에 포함되어야 하는 경우, 이를 최대한 이른 시간에 통합하십시오.
페이지 매핑
/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.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는 다음을 포함하는 Markdown 파일을 렌더링할 수 있습니다:
- YAML 프론트 매터에서
title을 사용하여 지정된 레벨 1 제목. 예를 들면,title: My Markdown file. GitLab 16.10에서 소개되었습니다. - Markdown에서 직접 지정된 레벨 1 제목. 예를 들면,
# My Markdown file.
동시에 두 가지 방법으로 페이지의 레벨 1 제목을 지정하지 않아야 하며, 그렇지 않으면 레벨 1 제목이 반복됩니다.
/help로의 링크
새로운 기능을 구축할 때 GitLab 애플리케이션에서 문서로 링크하려면, 일반적으로 app/views/ 디렉토리 내의 파일에서 help_page_path 도우미 메서드를 사용하여 수행합니다.
help_page_path에는 다음 규칙을 따라야 합니다:
- GitLab 저장소의
doc/디렉토리를 기준으로 합니다. - 명확성을 위해
.md파일 확장자로 끝나야 합니다.
도움말 텍스트는 Pajamas 가이드라인을 따릅니다.
HAML에서 /help로의 링크
맥락에 따라 특별한 경우를 사용하고 모든 링크 텍스트가 번역 가능하도록 _() 내에 있는지 확인하면서 다음과 같은 특수 경우를 사용할 수 있습니다:
-
문서 페이지에 링크하는 경우 가장 기본적인 형식에 따라
/help페이지로의 링크를 생성하는 HAML 코드는 다음과 같습니다:= link_to _('자세히 알아보기.'), help_page_path('user/permissions.md'), target: '_blank', rel: 'noopener noreferrer' -
앵커 링크로 링크하는 경우
anchor를help_page_path메서드의 일부로 사용합니다:= link_to _('자세히 알아보기.'), 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(_("이것은 옵션/기능을 설명하는 텍스트입니다. %{link_start}자세히 알아보기.%{link_end}"), tag_pair(link, :link_start, :link_end)) -
버튼 링크를 사용하는 경우. 텍스트가 페이지 레이아웃의 나머지와 맥락을 이루는 곳에 유용합니다:
= render Pajamas::ButtonComponent.new(variant: :default, href: help_page_path('user/group/import/index.md'), target: '_blank') do = _('자세히 알아보기')
JavaScript에서 /help로의 링크
JavaScript 또는 Vue 컴포넌트에서 문서로 링크하려면 help_page_helper.js의 helpPagePath 함수를 사용합니다:
import { helpPagePath } from '~/helpers/help_page_helper';
helpPagePath('user/permissions.md', { anchor: 'anchor-link' })
// GitLab.com의 경우 '/help/user/permissions#anchor-link'로 평가됩니다.
이는 정적 경로보다 선호되며 도우미는 상대 URL로 설치된 인스턴스에서도 작동합니다.
Ruby에서 /help 링크하기
Ruby 코드 내에서 문서에 링크하려면 다음 코드 블록을 참고하고, 모든 링크 텍스트가 _() 내에 있어 번역될 수 있도록 해야 합니다:
docs_link = link_to _('자세히 알아보기.'), help_page_url('user/permissions.md', 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.md', 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.
도움말