이미지, 다이어그램, 아이콘
GitLab v19.6요약
GitLab 문서는 두 가지 유형의 삽화를 사용합니다. 삽화는 독자가 개념, 복잡한 프로세스에서 자신의 위치, 또는 애플리케이션과 상호 작용하는 방법을 이해하는 데 도움이 될 수 있습니다. 문서에 삽화를 꼭 사용해야 한다면 삽화는 다음 조건을 갖춰야 합니다.
삽화#
GitLab 문서는 두 가지 유형의 삽화를 사용합니다.
- 스크린샷: GitLab 사용자 인터페이스의 일부를 보여 주는 데 사용합니다.
- 다이어그램: 프로세스나 개체 간의 관계를 설명하는 데 사용합니다.
삽화는 독자가 개념, 복잡한 프로세스에서 자신의 위치, 또는 애플리케이션과 상호 작용하는 방법을 이해하는 데 도움이 될 수 있습니다. 다음과 같은 이유로 삽화는 최소한으로 사용합니다.
- 시간이 지나면 오래된 정보가 됩니다.
- 현지화하기 어렵고 비용이 많이 듭니다.
- 스크린 리더가 읽을 수 없습니다.
문서에 삽화를 꼭 사용해야 한다면 삽화는 다음 조건을 갖춰야 합니다.
- 텍스트를 보완하되 대체하지 않아야 합니다. 독자가 필요한 정보를 얻기 위해 삽화에만 의존해서는 안 됩니다.
- 앞선 텍스트에 도입 문장이 있어야 합니다.
예를 들어
The following diagram illustrates the product analytics flow:입니다. - 접근할 수 있어야 합니다. 자세한 내용은 스크린샷과 다이어그램에 관한 지침을 참고합니다.
- 개인 식별 정보를 제외해야 합니다.
스크린샷#
관련 정보 중 일부를 텍스트로 전달할 수 없을 때 스크린샷으로 GitLab 사용자 인터페이스의 일부를 보여 줍니다.
스크린샷 캡처#
스크린샷을 찍을 때는 다음을 따릅니다.
- 스크린샷의 콘텐츠가 GitLab SAFE 프레임워크를 준수하는지 확인합니다. 확인하려면 SAFE 플로차트를 따릅니다.
- 가치를 제공하는지 확인합니다.
lorem ipsum텍스트를 사용하지 않습니다. 실제 시나리오에서 기능이 어떻게 사용될지 재현하고, 현실적인 텍스트를 사용합니다. - 관련 UI만 캡처합니다. 불필요한 공백이나 요점을 설명하는 데 도움이 되지 않는 UI 영역은 포함하지 않습니다. GitLab의 사이드바는 바뀔 수 있으므로 꼭 필요한 경우가 아니면 스크린샷에 포함하지 않습니다.
- 작게 유지합니다. 화면 전체 너비를 보여 줄 필요가 없다면 보여 주지 않습니다. 브라우저 창 크기를 최대한 줄여 요소들을 가까이 두고 빈 공간을 줄입니다. 스크린샷의 크기를 가능한 한 작게 유지합니다.
- 이미지가 페이지에서 어떻게 렌더링되는지 검토합니다. 이미지를 로컬에서 미리 보거나 머지 리퀘스트의 리뷰 앱을 사용합니다. 이미지가 흐릿하거나 부담스럽지 않은지 확인합니다.
- 일관성을 유지합니다. 일관된 읽기 경험을 위해 문서 페이지에 이미 있는 다른 스크린샷과 맞춥니다. 탐색 테마가 기본 설정인 Neutral로, 구문 강조 테마도 기본 설정인 Light로 설정되어 있는지 확인합니다.
콜아웃 추가#
스크린샷에서 한 영역을 강조하려면 화살표를 사용합니다.
- 색상은
#EE2604를 사용합니다. macOS의 미리 보기 애플리케이션을 사용한다면 이 색이 기본 빨간색입니다. - 선 굵기는 3pt를 사용합니다. macOS의 미리 보기 애플리케이션을 사용한다면 목록의 세 번째 선입니다.
- 다음 이미지에 나온 화살표 스타일을 사용합니다.
- 화살표가 여러 개라면 가능한 한 서로 평행하게 만듭니다.

이미지 요구 사항#
- 너비나 높이가 큰 스크린샷은 크기를 조정합니다.
- 너비는 1000픽셀 이하여야 합니다.
- 높이는 500픽셀 이하여야 합니다.
- 크기를 조정하고 압축한 뒤에도 스크린샷이 여전히 선명한지 확인합니다.
- JPEG 대신 PNG 이미지를 사용합니다.
- 모든 이미지는 100KB 이하로 압축해야 합니다. 많은 경우 이미지 품질을 떨어뜨리지 않고도 25-50KB 이하로 줄일 수 있습니다.
- 이미지에 담긴 기능이나 개념을 설명하는 소문자 파일 이름으로
이미지를 저장합니다.
- 이미지가 GitLab 인터페이스라면
image-name-vX_Y.png형식에 따라 파일 이름 끝에 GitLab 버전을 붙입니다. 예를 들어 GitLab 19.2의 파이프라인 페이지에서 찍은 스크린샷이라면pipelines-v19_2.png가 유효한 이름입니다. - 사용자 인터페이스의 일부를 포함하지 않는 삽화를 추가한다면
이미지가 추가된 릴리스에 해당하는 릴리스 번호를 붙입니다.
19.2 마일스톤에 추가된 MR이라면 삽화의 유효한 이름은
devops-diagram-v19_2.png입니다.
- 이미지가 GitLab 인터페이스라면
- 작업 중인
.md문서가 있는 디렉터리와 같은 디렉터리에img/라는 별도의 디렉터리를 만들어 이미지를 둡니다.- 외부에서 호스팅되는 이미지로 링크하지 않습니다. 사본을 내려받아 docs 디렉터리 안의 알맞은
img디렉터리에 저장합니다.
- 외부에서 호스팅되는 이미지로 링크하지 않습니다. 사본을 내려받아 docs 디렉터리 안의 알맞은
- GIF는 https://ezgif.com/optimize 또는 유사한 도구로 압축합니다.
문서를 설명하기 위해 동영상을 링크하고 임베드하는 방법도 참고합니다.
이미지 압축#
문서에 추가하는 새 이미지는 압축합니다. 이렇게 하면 파일 크기를 줄이고 페이지 로딩 성능을 개선하는 데 도움이 됩니다.
크로스 플랫폼이며 오픈 소스인 pngquant를 사용할 수 있습니다.
공식 웹사이트를 방문해 사용하는 OS의 안내에 따라
설치합니다.
이미지는 자동 또는 수동으로 압축할 수 있습니다.
- macOS에서 자동으로 압축하려면 스크린샷을 80% 줄이는 간단한 요령을 참고합니다.
- 수동으로 압축하려면
pngquant스크립트를 사용합니다.
pngquant 스크립트를 사용하려면 https://gitlab.com/gitlab-org/gitlab의 로컬 사본 루트 디렉터리에서
필요에 따라 다음 명령을 실행합니다.
-
모든 문서 PNG 이미지가 압축되었는지 확인하려면 다음을 실행합니다.
bin/pngquant lint -
모든 문서 PNG 이미지를 압축하려면 다음을 실행합니다.
bin/pngquant compress -
특정 파일을 압축하려면 다음을 실행합니다.
bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png -
특정 디렉터리의 모든 PNG 파일을 압축하려면 다음을 실행합니다.
bin/pngquant compress doc/user/img
이미지 파일을 PNG 형식으로 변환#
압축 스크립트가 제자리에서 압축하는 대신 .compressed 파일을 만든다면
해당 파일은 PNG 확장자를 가졌지만 실제로는 다른 이미지 형식(JPEG 등)일 가능성이 높습니다.
png_quantizator gem은 PNG가 아닌 파일에서 충돌하여 스크립트가 완료되지 못합니다.
사전 요구 사항:
-
GraphicsMagick을 설치합니다.
# macOS: brew install graphicsmagick
이미지 파일을 PNG 형식으로 변환하려면 다음을 따릅니다.
-
파일 형식을 확인합니다.
file doc/user/img/problematic_file.pngfile명령은 확장자가 아니라 파일 내용(매직 바이트/헤더)을 검사합니다. 이름이 잘못 붙은 JPEG 파일은 다음과 같이 표시됩니다.doc/user/img/problematic_file.png: JPEG image data, JFIF standard 1.01... -
GraphicsMagick을 사용해 파일을 PNG 형식으로 변환합니다.
gm convert problematic_file.png corrected_file.png -
압축 스크립트를 다시 실행합니다.
원본이 JPEG 파일이었다면 PNG는 무손실 압축을 사용하고 JPEG는 손실 압축을 사용하므로 변환된 PNG 파일이 더 크게 나타날 수 있습니다.
이미지 삭제#
영문 문서에서 이미지 참조를 제거할 때 이미지 파일을 삭제하지 않습니다. 현지화된 문서(예: 일본어 페이지)는 영문 문서와 같은 이미지 파일을 사용합니다. 영문 문서에서 이미지를 더 이상 참조하지 않더라도 번역된 페이지에서는 여전히 사용 중일 수 있습니다.
문서 사이트 빌드 프로세스는 이미지 경로를 검사합니다. 아직 사용 중인 이미지를 삭제하면
머지 리퀘스트 파이프라인의 hugo_build job이 실패합니다.
어디에서도 사용되지 않는 이미지는 월간 유지 관리의 일부로 정리됩니다.
애니메이션 이미지#
애니메이션 이미지(애니메이션 GIF 등)는 피합니다. 사용자에게 주의를 분산시키고 성가시게 할 수 있습니다.
사용자 인터페이스의 복잡한 상호 작용을 설명하면서 독자의 이해를 돕는 시각적 표현을 포함하고 싶다면 다음을 할 수 있습니다.
- 정적 이미지(스크린샷)를 사용하고, 필요하면 콜아웃을 추가해 화면의 한 영역을 강조합니다.
- 상호 작용을 담은 짧은 동영상을 만들어 링크합니다.
콘텐츠에 이미지 링크 추가#
문서에 이미지를 포함하는 Markdown 코드는 다음과 같습니다.

대체 텍스트#
대체 텍스트는 접근성 있는 경험을 제공합니다. 스크린 리더는 대체 텍스트로 이미지를 설명하며, 이미지를 내려받지 못하면 대체 텍스트가 표시됩니다.
대체 텍스트는 이미지의 내용이 아니라 이미지의 맥락을 설명해야 합니다. 페이지나 섹션의 주제와 관련된 맥락을 추가합니다. 누군가가 이미지를 볼 수 없는 상태에서 페이지를 읽고 상호 작용하도록 돕는다면 이미지에 대해 무엇이라고 말할지 생각해 봅니다.
올바른 예:

잘못된 예:

대체 텍스트를 작성할 때는 다음을 따릅니다.
- 짧고 설명적인 대체 텍스트를 155자 이하로 작성합니다. 스크린 리더는 보통 이 글자 수를 넘으면 읽기를 멈춥니다.
- 이미지에 워크플로 다이어그램처럼 복잡한 정보가 있다면 짧은 대체 텍스트로 이미지를 식별하고 자세한 정보는 본문에 포함합니다.
- 문장이든 아니든 문자열 끝에 마침표를 사용합니다.
- 문장형 대소문자를 사용하고 모두 대문자로 쓰는 것을 피합니다. 일부 스크린 리더는 대문자를 개별 글자로 읽습니다.
- Image of나 Graphic of 같은 문구를 사용하지 않습니다.
- 키워드 나열을 사용하지 않습니다. 맥락을 보강하려면 본문에 키워드를 포함합니다.
- 이미지는 대체 텍스트가 아니라 주제에서 소개합니다.
- 주제에서 이미 사용한 텍스트를 반복하지 않도록 합니다.
- 굵게, 기울임꼴, 백틱 같은 인라인 스타일을 사용하지 않습니다.
스크린 리더는
**text**를star star text star star로 읽습니다. - 이미지가 페이지에 고유한 정보를 더하지 않는다면 태그를 아예 생략하지 말고 빈 대체 텍스트 태그(
alt="")를 사용합니다. 예를 들어 이미지가 장식용이거나 본문 텍스트나 캡션에서 이미 충분히 설명된 경우입니다. 빈 alt 태그는 보조 기술에 텍스트를 의도적으로 생략했음을 알리지만, alt 태그가 없으면 의도가 모호합니다.
자동 스크린샷 생성기#
자동 스크린샷 생성기를 사용해 스크린샷을 찍고 압축할 수 있습니다.
- GitLab Development Kit(GDK)를 설정합니다.
- 복제한 GitLab 리포지터리가 있는 하위 디렉터리(보통
gdk/gitlab)로 이동합니다. - GDK 데이터베이스가 완전히 마이그레이션되었는지 확인합니다:
bin/rake db:migrate RAILS_ENV=development. pngquant를 설치합니다. 자세한 내용은 도구 웹사이트를 참고합니다:pngquantscripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>을 실행합니다.- 스크립트의
it매개변수로 정의한gitlab/doc위치를 기준으로 스크린샷의 위치를 확인합니다. - 새로 만든 스크린샷을 커밋합니다.
도구 확장#
스크린샷 생성기를 추가하려면 다음을 따릅니다.
-
spec/docs_screenshots디렉터리에 확장자가_docs.rb인 새 파일을 추가합니다. -
파일에 다음 정보를 추가합니다.
require 'spec_helper' RSpec.describe '', :js do include DocsScreenshotHelpers # Helper that enables the screenshots taking mechanism before do page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page end -
각
it블록에 스크린샷을 저장할 경로를 추가합니다.it '<path/to/images/directory>'
visit <path>로 페이지의 스크린샷을 찍을 수 있습니다.
빈 스크린샷을 방지하려면 expect를 사용해 콘텐츠가 로드될 때까지 기다립니다.
단일 요소 스크린샷
단일 요소의 스크린샷을 찍을 수 있습니다.
-
스크린샷 생성기 파일에 다음을 추가합니다.
screenshot_area = find('<element>') # Find the element scroll_to screenshot_area # Scroll to the element expect(screenshot_area).to have_content '<content>' # Wait for the content you want to capture set_crop_data(screenshot_area, <padding>) # Capture the element with added padding
자체 스크립트를 만들 때 spec/docs_screenshots/container_registry_docs.rb를 가이드로 사용합니다.
다이어그램#
정보가 텍스트만으로 이해하기에 너무 복잡하다면 다이어그램으로 프로세스나 개체 간의 관계를 설명합니다.
다이어그램을 만들려면 다음 중 하나를 사용합니다.
Mermaid는 권장하는 다이어그램 도구이지만 모든 상황에 적합하지는 않습니다. 예를 들어 복잡한 다이어그램 요구 사항 때문에 이해하기 어려운 레이아웃이 만들어질 수 있습니다.
GUI 다이어그램 도구는 작성자가 Mermaid의 복잡성과 레이아웃 문제를 극복하도록 도울 수 있습니다. Draw.io는 편집기를 사용할 때 다이어그램과 그 정의가 모두 SVG 파일에 저장되어 편집할 수 있으므로 선호하는 GUI 도구입니다. Draw.io는 GitLab 위키와도 통합되어 있습니다.
| 기능 | Mermaid | Draw.io |
|---|---|---|
| 필요한 편집기 | 텍스트 편집기 | Draw.io 편집기 |
| WYSIWYG 편집 | [dash-circle] 아니요 | [check-circle-filled] 예 |
grep으로 텍스트 콘텐츠 검색 가능 |
[check-circle-filled] 예 | [dash-circle] 아니요 |
| 모양을 제어하는 주체 | 웹사이트의 CSS | 다이어그램 작성자 |
| 파일 형식 | SVG | SVG |
| VS Code 통합(확장 사용) | [check-circle-filled] 예(미리 보기 및 로컬 편집) | [check-circle-filled] 예(미리 보기 및 로컬 편집) |
| 동적 생성 | [check-circle-filled] 예 | [dash-circle] 아니요 |
다이어그램 지침#
접근성 있고 유지 관리하기 쉬운 다이어그램을 만들려면 다음 지침을 따릅니다.
-
다이어그램을 단순하고 초점이 분명하게 유지합니다. 꼭 필요한 요소와 정보만 포함합니다.
-
요소를 구분할 때는 도형만 사용합니다. 다이어그램은 라이트 모드와 다크 모드에서 모두 호환되어야 하므로 색상으로 요소를 구분하지 않습니다.
권장 도형은 다음과 같습니다.
- 프로세스나 단계에는 직사각형.
- 결정 지점에는 마름모.
- 요소 간의 직접적인 관계에는 실선.
- 요소 간의 간접적인 관계에는 점선.
- 프로세스의 흐름이나 방향에는 화살표.
-
같은 요소를 나타내는 도형은 모양과 크기가 같아야 합니다.
-
다이어그램 요소에 명확한 레이블과 간단한 설명을 추가합니다.
-
텍스트가 있는 요소는 텍스트와 도형의 윤곽선 사이에 충분한 여백이 있는지 확인합니다. 필요하다면 도형과 다이어그램의 모든 유사한 도형의 크기를 키웁니다.
-
다이어그램에 제목과 간단한 설명을 포함합니다.
-
텍스트에는 GitLab Sans 글꼴을 사용하고, 대체 옵션으로 Google Inter 글꼴을 사용합니다.
-
복잡한 프로세스는 큰 다이어그램 하나 대신 단순한 다이어그램 여러 개를 만드는 것을 고려합니다.
-
다이어그램이 다양한 기기와 화면 크기에서 잘 표시되는지 검증합니다.
-
링크를 포함하지 않습니다.
click동작으로 다이어그램에 삽입한 링크는 GitLab의 링크 검사 도구로 테스트할 수 없습니다. -
프로세스가 바뀌면 정확성을 유지하도록 문서나 코드와 함께 다이어그램을 업데이트합니다.
Mermaid로 다이어그램 만들기#
Mermaid 구문으로 다이어그램을 만드는 방법은 Mermaid 사용자 가이드와 Mermaid 사이트의 예시를 참고합니다.
Mermaid로 GitLab 문서용 다이어그램을 만들려면 다음을 따릅니다.
-
Mermaid Live Editor에서 다이어그램을 만듭니다.
-
Code 창의 내용을 복사해
mermaid코드 블록으로 감싸 Markdown 파일에 붙여넣습니다. 자세한 내용은 Mermaid용 GitLab Flavored Markdown을 참고합니다. -
다이어그램 유형을 선언한 줄(
flowchart나sequenceDiagram등)의 다음 줄에 접근성을 위해 다음 줄을 추가합니다.accTitle: your diagram title here accDescr: describe what your diagram does in a single sentence, with no line breaks.제목과 설명이 대체 텍스트 지침을 따르는지 확인합니다.
예를 들어 다음 플로차트에는 접근성 정보가 포함되어 있습니다.
<div class="diagram-placeholder"><div class="diagram-placeholder-header">Mermaid 다이어그램 (5줄)</div><details><summary>소스 코드 보기</summary><pre><code>flowchart TD
accTitle: Example diagram title
accDescr: A description of your diagram
A[Start here] -->|action| B[next step]</code></pre></details></div>
Draw.io로 다이어그램 만들기#
다이어그램을 만들려면 Draw.io 웹 애플리케이션이나 (비공식) VS Code Draw.io Integration 확장을 사용합니다. 두 도구 모두 같은 다이어그램 편집 경험을 제공하지만 웹 애플리케이션은 편집 가능한 예시 다이어그램을 제공합니다.
Draw.io로 만든 다이어그램은 일반 다이어그램 지침과 Draw.io 전용 지침을 준수해야 합니다.
Draw.io 지침#
Draw.io에서 다이어그램을 만들 때는 Mermaid로 만든 다이어그램과 시각적으로 일관되어야 합니다. 다음 규칙은 일반 다이어그램 지침에 추가되는 규칙입니다.
글꼴:
- 모든 텍스트에 Inter 글꼴을 사용합니다. 이 글꼴은 기본 글꼴에 포함되어 있지 않습니다.
Inter 글꼴을 사용자 지정 글꼴로 추가하려면 다음을 따릅니다.
- 글꼴 드롭다운 목록에서 Custom을 선택합니다.
- Google fonts를 선택하고 Font name 텍스트 상자에
Inter를 입력합니다.
도형:
- 요소에는 직사각형 도형을 사용합니다.
- 플로차트에는 Flowchart 도형 컬렉션의 도형을 사용합니다.
웹 애플리케이션 사용#
Draw.io 웹 애플리케이션으로 다이어그램을 만들려면 다음을 따릅니다.
- Draw.io 웹 애플리케이션에서 다이어그램을 만듭니다.
- 다이어그램을 저장합니다.
- Draw.io 웹 애플리케이션에서 File > Export as > SVG를 선택합니다.
- Include a copy of my diagram: All pages 체크박스를 선택한 다음 Export를 선택합니다.
Draw.io에서 편집할 수 있음을 나타내도록 파일 확장자
drawio.svg를 사용합니다.
- SVG를 이미지로 문서에 추가합니다. 이러한 SVG는 SVG가 아닌 다른 이미지와 같은 Markdown을 사용합니다.
VS Code 확장 사용#
VS Code용 Draw.io Integration 확장으로 다이어그램을 만들려면 다음을 따릅니다.
-
다이어그램을 담을 디렉터리에 접미사가
drawio.svg인 빈 파일을 만듭니다. -
VS Code에서 파일을 열고 다이어그램을 만듭니다.
-
파일을 저장합니다.
다이어그램의 정의는 Draw.io와 호환되는 형식으로 SVG 파일에 저장됩니다.
-
SVG를 이미지로 문서에 추가합니다. 이러한 SVG는 SVG가 아닌 다른 이미지와 같은 Markdown을 사용합니다.
GitLab SVG 아이콘#
GitLab SVG 라이브러리의 아이콘을
문서에서 직접 사용할 수 있습니다. 예를 들어 는 다음과 같이 렌더링됩니다: [tanuki].
대부분의 경우 텍스트에서 아이콘은 피합니다. 다만 호버 텍스트가 UI 요소를 설명할 수 있는 유일한 방법이라면 아이콘을 사용합니다. 예를 들어 Delete나 Edit 버튼에는 호버 텍스트만 있는 경우가 많습니다.
아이콘을 사용할 때는 호버 텍스트로 시작하고 그 뒤에 괄호로 SVG 참조를 붙입니다.
- 피해야 할 표현:
Select **Edit**.렌더링 결과: Select ✏️ Edit. - 대신 사용할 표현:
Select **Edit** ().렌더링 결과: Select Edit (✏️).
단어로 아이콘을 설명하지 않습니다.
- 피해야 할 표현:
Select **Erase job log** (the trash icon). - 대신 사용할 표현:
Select **Erase job log** ().렌더링 결과: Select Erase job log ([remove]).
버튼에 호버 텍스트가 없다면 아이콘을 설명합니다. 이어서 접근성을 개선하기 위해 버튼에 호버 텍스트를 추가하도록 UX 버그 이슈를 만듭니다.
- 피해야 할 표현:
Select . - 대신 사용할 표현:
Select the vertical ellipsis ().렌더링 결과: Select the vertical ellipsis (⋮).