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형 릴리스가 변경될 수 있습니다.

예를 들어:

  1. gitlab의 Merge Request이 문서를 업데이트합니다. 14.4 버전의 마일스톤이 있으며, 2021-10-22에 예정된 릴리스 날짜를 가지고 있습니다.
  2. 2021-10-19에 Merge되고, 같은 날 https://docs.gitlab.com에서 온라인으로 이용할 수 있습니다.
  3. 2021-10-22에 GitLab 14.4가 릴리스되며, 2021-10-18의 gitlab 코드베이스를 기반으로합니다(업데이트가 Merge된 날짜보다 하루 이전).
  4. 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 파일

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입니다.