링크와 비디오
GitLab v19.6요약
링크는 독자가 필요한 내용을 찾도록 돕는 중요한 수단입니다. 그러나 대부분의 콘텐츠는 검색으로 찾으므로, 한 페이지에 링크를 너무 많이 넣지 않아야 합니다. 참조 링크 대신 인라인 링크를 사용합니다. 같은 리포지터리에 있는 다른 문서(.md) 파일로 링크하려면 다음과 같이 합니다.
링크#
링크는 독자가 필요한 내용을 찾도록 돕는 중요한 수단입니다.
그러나 대부분의 콘텐츠는 검색으로 찾으므로, 한 페이지에 링크를 너무 많이 넣지 않아야 합니다. 링크가 너무 많으면 가독성이 떨어질 수 있습니다.
- 같은 페이지에서 링크를 중복하지 않습니다. 예를 들어 페이지 A에서 페이지 B로 여러 번 링크하지 않습니다.
- 제목에는 링크를 사용하지 않습니다. 링크가 들어간 제목은 오류를 일으킵니다.
- 링크 안의 단어 사이에서 강제로 줄을 바꾸지 않습니다.
- 한 문단에 링크를 여러 개 넣지 않도록 합니다.
- 한 작업에 링크를 여러 개 넣지 않도록 합니다.
- 한 페이지에서 다른 페이지로 연결하는 링크는 15개를 넘기지 않도록 합니다.
- 작업 흐름을 방해하는 링크를 줄이려면 관련 주제를 사용하는 방안을 고려합니다.
- 같은 페이지의 섹션으로 연결하는 앵커 링크는 가급적 사용하지 않습니다. 사용자가 오른쪽 탐색을 활용하도록 합니다.
인라인 링크#
참조 링크 대신 인라인 링크를 사용합니다. 인라인 링크가 해석하고
수정하기 더 쉽습니다.
(Vale 규칙: ReferenceLinks.yml)
-
권장:
For more information, see [merge requests](path/to/merge_requests.md) -
비권장:
For more information, see [merge requests][1]. [1]: path/to/merge_requests.md
같은 리포지터리 안의 링크#
같은 리포지터리에 있는 다른 문서(.md) 파일로 링크하려면 다음과 같이 합니다.
- 상대 파일 경로를 사용한 인라인 링크를 사용합니다. 예:
[GitLab.com settings](../user/gitlab_com/_index.md). - 링크가 매우 길더라도 링크 전체를 한 줄에 넣습니다. (Vale 규칙:
MultiLineLinks.yml)
GitLab 리포지터리에서는 다른 어떤 디렉터리에서도 /development 디렉터리로 링크하지 않습니다.
개발 문서에서 특정 코드 파일로 링크하는 경우처럼 문서 파일 밖의 파일로 링크하려면 다음과 같이 합니다.
- 전체 URL을 사용합니다. 예:
[`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/views/help/show.html.haml) - 선택 사항입니다. 특정 ref가 포함된 전체 URL을 사용합니다. 예:
[`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/6d01aa9f1cfcbdfa88edf9d003bd073f1a6fff1d/app/views/help/show.html.haml)
별도 리포지터리의 링크#
다른 리포지터리에 있는 페이지로 링크하려면 전체 URL을 사용합니다.
예를 들어 GitLab 리포지터리의 페이지에서 Charts 리포지터리로 링크하려면
[GitLab Charts documentation](https://docs.gitlab.com/charts/) 같은 URL을 사용합니다.
앵커 링크#
각 주제 제목에는 앵커 링크가 있습니다. 예를 들어 제목이
## This is an example인 주제의 앵커는 #this-is-an-example입니다.
주제 제목 텍스트를 바꾸면 앵커 링크도 바뀝니다. 링크가 깨지지 않도록 다음을 지킵니다.
- 주제 제목에 단계 번호를 사용하지 않습니다.
- 가능하면 나중에 바뀔 수 있는 단어를 사용하지 않습니다.
링크와 제목 변경#
주제 제목을 바꾸면 앵커 링크가 바뀝니다. 다른 문서 페이지나 코드 파일이 이 앵커로 링크하고 있으면 파이프라인 job이 실패할 수 있습니다.
파이프라인 실패를 막으려면 변경 사항을 푸시하기 전에 링크 검사를 로컬에서 실행하는 방안을 고려합니다.
링크 텍스트#
링크 텍스트는 다음 지침을 따릅니다.
UI에 표시되는 링크 텍스트 작성 방법은 Pajamas를 참고합니다.
표준 텍스트#
다음 패턴 중 하나를 따르는 텍스트를 사용합니다.
For more information, see [link text](link.md).To [DO THIS THING], see [link text](link.md)
예:
For more information, see [merge requests](link.md).To create a review app, see [review apps](link.md).
이 텍스트를 확장하려면
For more information about this feature, see... 같은 문구를 사용합니다.
다음 구문은 사용하지 않습니다.
Learn more about...To read more....For more information, see the [Merge requests](link.md) page.For more information, see the [Merge requests](link.md) documentation.
here 대신 설명하는 텍스트#
링크에는 here나 this page. 같은 단어 대신 설명하는 텍스트를 사용합니다.
주제나 페이지의 이름은 소문자로 씁니다.
텍스트가 주제나 페이지 이름과 정확히 일치하지 않아도 됩니다.
설명이 되고 지침에 맞도록 텍스트를 수정합니다.
권장:
For more information, see [merge requests](link.md).For more information, see [roles and permissions](link.md).For more information, see [how to configure common settings](link.md).
비권장:
For more information, see [this page](link.md).For more information, go [here](link.md).For more information, see [this documentation](link.md).
이슈 링크#
이슈로 링크할 때는 링크에 이슈 번호를 포함합니다. 예:
For more information, see [issue 12345](link.md).
번호 기호(issue #12345)는 사용하지 않습니다.
API 링크#
API 문서로 링크할 때는 소문자를 사용합니다. 예:
To import your GitHub repository, see the [import API](link.md).
페이지 제목에 맞추려고 첫 글자를 대문자로 쓰지 않습니다. 예를 들어 다음과 같이 쓰지 않습니다.
To import your GitHub repository, see the [Import API](link.md).
외부 문서 링크#
가능하면 외부 문서로 링크하지 않습니다. 이런 링크는 오래되기 쉽고 유지 관리하기 어렵습니다.
링크가 꼭 필요한 경우도 있습니다. 문제 해결 단계를 명확하게 하거나 콘텐츠 중복을 막는 데 도움이 될 수 있습니다. 외부 문서가 더 정확하고 더 적극적으로 유지 관리되는 경우도 있습니다.
외부 링크를 추가할 때마다 고객이 얻는 이점과 유지 관리의 어려움을 비교합니다.
핸드북 링크#
핸드북 링크는 제한합니다. 라이선스 약관, 데이터 사용 및 접근 정책, 테스트 계약, 이용 약관처럼 피할 수 없는 링크도 있습니다.
기밀 또는 접근 제한 링크#
다음으로 직접 링크하지 않습니다.
이런 링크는 다음 경우에 실패합니다.
- 권한이 충분하지 않은 사용자.
- 자동 링크 검사기.
이런 링크를 꼭 사용해야 하는 경우 다음과 같이 합니다.
- 링크가 기밀 이슈나 내부 핸드북 페이지로 연결되면, 해당 이슈나 페이지가 GitLab 팀 구성원에게만 보인다고 언급합니다.
- 링크를 보려면 특정 권한이나 역할이 필요하면, 그 정보를 언급합니다.
- 링크 검사기가 실패하지 않도록 링크를 백틱으로 감쌉니다.
예:
-
GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>` -
GitLab team members can view more information in this internal handbook page: `https://internal.gitlab.com/handbook/<link>` -
Users with the Maintainer role for the project can use the pipeline editor: `https://gitlab.com/gitlab-org/gitlab/-/ci/editor`
특정 코드 줄 링크#
파일의 특정 줄로 링크할 때는 브랜치 대신 커밋으로 링크합니다. 코드 줄은 시간이 지나면 바뀝니다. 커밋 링크를 사용해 줄로 링크하면 사용자가 의도한 줄에 도착합니다. 프로젝트에서 파일을 볼 때 표시되는 줄임표 메뉴의 Permalink 드롭다운 항목이 해당 파일의 가장 최근 커밋 링크를 제공합니다.
- 권장:
[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3) - 비권장:
[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).
추가 커밋으로 링크된 표현식의 줄 번호가 바뀌었더라도 파일에서 해당 쿼리를 검색할 수 있습니다. 이 경우 문서가 파일의 가장 최근 버전으로 링크하도록 업데이트합니다.
비디오#
GitLab YouTube 비디오 튜토리얼을 문서에 추가하는 것을 강력히 권장합니다. 단, 비디오가 오래된 경우는 제외합니다. 비디오는 문서를 대체하지 않고 보완하거나 설명하는 용도로 사용합니다. 비디오의 내용이 기능과 핵심 사용 사례에 기본이 되는데 문서에 충분히 다뤄져 있지 않다면 다음을 수행합니다.
- 이 세부 내용을 문서 텍스트에 추가합니다.
- 비디오를 검토하고 페이지를 업데이트하는 이슈를 만듭니다.
비디오를 제품 리포지터리에 업로드하지 않습니다. 대신 링크를 추가하거나 임베드합니다.
비디오 링크#
비디오로 링크할 때는 독자가 페이지를 읽기 전에 비디오를 훑어볼 수 있도록 YouTube 아이콘을 포함합니다. 링크 텍스트는 일반 지침을 따릅니다. 오래되었을 수 있는 비디오를 식별할 수 있도록 링크 뒤에 비디오 게시 날짜를 포함합니다.
<i class="fa-youtube-play" aria-hidden="true"></i>
For an overview, see [merge requests](https://link-to-video).
<!-- Video published on YYYY-MM-DD -->
GitLab 사용자에게 유용한 최신 비디오라면 어떤 것이든 링크할 수 있습니다.
비디오 임베드#
GitLab 문서 사이트는 임베드된 비디오를 지원합니다.
GitLab 공식 YouTube 계정의 비디오만 임베드할 수 있습니다. 다른 출처의 비디오는 대신 링크합니다.
임베드된 비디오는 페이지에서 많은 공간을 차지하고 독자의 집중을 흐릴 수 있으므로, 대부분의 경우 비디오로 링크합니다.
비디오를 임베드하려면 다음과 같이 합니다.
- 이 절차의 코드를 복사해 Markdown 파일에 붙여넣습니다. 코드 위아래에 빈 줄을 둡니다. 코드를 수정하지 않습니다(공백을 삭제하거나 추가하지 않습니다).
- YouTube에서 표시하려는 비디오 URL로 이동합니다. 브라우저에서 일반 URL
(
https://www.youtube.com/watch?v=VIDEO-ID)을 복사해<div class="video-fallback">아래 줄의 비디오 제목과 링크를 바꿉니다. - YouTube에서 Share를 선택한 다음 Embed를 선택합니다.
<iframe>소스(src) URL만 (https://www.youtube-nocookie.com/embed/VIDEO-ID) 복사해iframe태그의src필드 내용을 대체하도록 붙여넣습니다.- 오래되었을 수 있는 비디오를 식별할 수 있도록 링크 아래에 비디오 게시 날짜를 포함합니다.
leave a blank line here
<div class="video-fallback">
See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
</div>
<figure class="video-container">
<iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe>
</figure>
<!-- Video published on YYYY-MM-DD -->
leave a blank line here
GitLab 문서 사이트에서는 다음과 같이 렌더링됩니다.
이 형식에는 다음 이유가 있습니다.
figure태그는 시맨틱 SEO에 필요하며,video-container클래스는 비디오가 반응형으로 동작하고 여러 모바일 기기에서 표시되도록 하는 데 필요합니다.<div class="video-fallback">는/help에 필요한 대체 수단입니다. GitLab Markdown 프로세서가 iframe을 지원하지 않기 때문입니다. 문서 사이트에서는 숨겨지지만/help에서는 표시됩니다.www.youtube-nocookie.com도메인은 YouTube 임베드 플레이어의 개인정보 보호 강화 모드를 활성화합니다. 이 모드에서는 쿠키 설정이 제한된 사용자도 임베드된 비디오를 볼 수 있습니다.
클릭 스루 데모 링크#
클릭 스루 데모로 링크할 때는 비디오와 비슷한 지침을 따릅니다.
For a click-through demo, see [Demo Title](https://link-to-demo).
<!-- Demo published on YYYY-MM-DD -->