• 페이지 매핑
  • _index.md 파일
• 소스 파일
• /help에 링크하기
  • HAML에서 /help에 링크하기
  • JavaScript에서 /help에 링크하기
  • Ruby에서 /help에 링크하기
• /help 테스트

GitLab /help

모든 GitLab 인스턴스는 /help에 문서가 포함되어 있으며 (https://gitlab.example.com/help) 인스턴스의 버전과 일치합니다. 예를 들어, https://gitlab.com/help.

온라인에서 사용할 수 있는 문서는 https://docs.gitlab.com에서 기본 브랜치인 GitLab, Omnibus, Runner, Charts 및 Operator에서 매시간 배포됩니다. 문서를 업데이트하는 병합 요청이 병합되면, 한 시간 이내에 온라인에서 사용 가능합니다.

그러나 자가 관리 인스턴스의 경우 다음 릴리즈 버전에서만 /help에서 사용할 수 있습니다. 업데이트가 병합된 날짜는 업데이트가 포함되는 자가 관리 릴리즈에 영향을 줄 수 있습니다.

예를 들어:

1. gitlab에서 문서를 업데이트하는 병합 요청이 있습니다. 이 요청은 14.4 마일스톤이 있으며, 예상 릴리즈 날짜는 2021-10-22입니다.
2. 2021-10-19에 병합되어 같은 날 https://docs.gitlab.com에서 사용할 수 있습니다.
3. GitLab 14.4는 2021-10-22에 릴리즈 되며, gitlab 코드베이스는 2021-10-18 기준입니다. (업데이트가 병합되기 하루 전).
4. 변경 사항은 14.5 자가 관리 릴리즈에 나타납니다, 14.4의 릴리즈 마감일을 놓쳤기 때문입니다.

문서 업데이트가 이번 달 릴리즈에 포함되는 것이 중요하다면, 가능한 한 빨리 병합하십시오.

페이지 매핑

/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에 대한 요청을 매핑합니다.

• 요청된 경우, 파일이 요청된 위치에 존재하면 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는 다음 방법으로 레벨 1 제목이 지정된 Markdown 파일을 렌더링할 수 있습니다:

• YAML 프론트 매터에서 title을 사용하여 지정합니다. 예: title: My Markdown file. GitLab 16.10에서 도입되었습니다.
• Markdown 자체에서 지정합니다. 예: # My Markdown file.

페이지의 레벨 1 제목을 두 방법으로 동시에 지정해서는 안 되며, 그렇지 않으면 레벨 1 제목이 반복됩니다.

/help에 링크하기

새 기능을 구축할 때 GitLab 애플리케이션에서 문서에 링크해야 할 수도 있습니다. 이는 일반적으로 app/views/ 디렉토리 내의 파일에서 help_page_path 헬퍼 메서드를 사용하여 수행됩니다.

help_page_path는 링크하고자 하는 문서의 경로를 포함하며, 다음 규칙을 따릅니다:

• GitLab 리포지토리의 doc/ 디렉토리에 상대적입니다.
• 명확성을 위해 .md 파일 확장자로 끝나야 합니다.

헬프 텍스트는 Pajamas 가이드라인을 따릅니다.

HAML에서 /help에 링크하기

다음 특별한 경우를 사용하여 문맥에 따라 모든 링크 텍스트가 번역될 수 있도록 _() 안에 있어야 합니다:

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

  = link_to _('더 알아보기.'), help_page_path('user/permissions.md'), target: '_blank', rel: 'noopener noreferrer'
  

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

  = 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 테스트

여러 RSpec 테스트가 실행되어 GitLab 문서가 올바르게 렌더링되고 작동하는지 확인합니다.

특히, 메인 문서 랜딩 페이지가 /help에서 올바르게 작동합니다.

예를 들어, GitLab.com의 /help.