위키

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

문서를 리포지토리에 보관하지 않으려는 경우, 코드와 동일한 프로젝트에 보관하고 싶다면, 각 GitLab 프로젝트에서 제공하는 위키를 사용할 수 있습니다. 모든 위키는 별도의 Git 리포지토리이므로, 웹 인터페이스를 통해 위키 페이지를 생성하거나, 로컬에서 Git을 사용하여 작성할 수 있습니다.

GitLab 위키는 콘텐츠를 위해 Markdown, RDoc, AsciiDoc, Org를 지원합니다. Markdown으로 작성된 위키 페이지는 모든 Markdown 기능을 지원하며, 링크에 대한 위키 전용 동작도 제공합니다.

위키 페이지는 사이드바도 표시하며, 사용자 설정이 가능합니다.

프로젝트 위키 보기

프로젝트 위키에 접근하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 위키를 표시하려면, 다음 중 하나를 선택하세요:
    • 왼쪽 사이드바에서 Plan > Wiki를 선택합니다.
    • 프로젝트의 모든 페이지에서 g + w 위키 키보드 단축키를 사용합니다.

프로젝트의 왼쪽 사이드바에 Plan > Wiki가 표시되지 않는 경우, 프로젝트 관리자에 의해 비활성화되었습니다.

위키의 기본 브랜치 구성

위키 리포지토리의 기본 브랜치는 GitLab 버전에 따라 다릅니다:

  • GitLab 버전 14.1 이상: 위키는 인스턴스 또는 그룹에 대해 구성된 기본 브랜치 이름을 상속받습니다. 사용자 지정 값이 구성되지 않은 경우, GitLab은 main을 사용합니다.
  • GitLab 버전 14.0 이하: GitLab은 master를 사용합니다.

모든 GitLab 버전에서, 이전에 생성된 위키에 대해 이 기본 브랜치 이름을 변경할 수 있습니다.

위키 홈 페이지 생성

  • 페이지 제목과 경로의 분리 소개됨 GitLab 17.2에서 wiki_front_matter 및 wiki_front_matter_title이라는 플래그와 함께. 기본값으로 활성화됨.
  • 기능 플래그 wiki_front_matter 및 wiki_front_matter_title은 GitLab 17.3에서 제거되었습니다.

위키가 생성될 때, 비어 있습니다. 처음 방문할 때, 사용자가 위키를 볼 때 볼 수 있는 홈 페이지를 생성할 수 있습니다. 이 페이지는 위키의 홈 페이지로 사용되는 특정 경로가 필요합니다. 생성하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾으세요.
  2. Plan > Wiki를 선택합니다.
  3. Create your first page를 선택합니다.
  4. 선택 사항. 홈 페이지의 제목을 변경합니다.
  5. GitLab은 이 첫 페이지에 경로 home이 필요합니다. 이 경로의 페이지는 위키의 첫 번째 페이지로 사용됩니다.
  6. 텍스트 스타일링을 위한 형식을 선택합니다.
  7. 홈 페이지의 내용 섹션에 환영 메시지를 추가합니다. 언제든지 나중에 편집할 수 있습니다.
  8. 커밋 메시지를 추가합니다. Git은 커밋 메시지가 필요하므로, GitLab이 자동으로 생성합니다.
  9. 페이지 생성을 선택합니다.

새로운 위키 페이지 만들기

  • 페이지 제목과 경로의 분리 소개됨 GitLab 17.2에서 wiki_front_matter 및 wiki_front_matter_title라는 플래그와 함께. 기본적으로 활성화되어 있습니다.
  • 기능 플래그 wiki_front_matter 및 wiki_front_matter_title는 GitLab 17.3에서 제거되었습니다.

전제 조건:

  • 최소한 Developer 역할을 가지고 있어야 합니다.

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.

  2. 계획 > 위키를 선택합니다.

  3. 위키 작업 ( )을 선택한 다음, 이 페이지 또는 다른 위키 페이지에서 새 페이지를 선택합니다.

  4. 콘텐츠 형식을 선택합니다.

  5. 새 페이지에 대한 제목을 추가합니다.

  6. 선택 사항. 제목에서 페이지 경로 생성 체크를 해제하고 페이지의 경로를 변경합니다.
    페이지 경로는 하위 디렉토리 및 형식을 위해 특수 문자를 사용하며,
    길이 제한이 있습니다.

  7. 선택 사항. 위키 페이지에 내용을 추가합니다.

  8. 선택 사항. 파일을 첨부하면 GitLab이 위키의 Git 저장소에 저장합니다.

  9. 커밋 메시지를 추가합니다. Git은 커밋 메시지를 요구하므로, 당신이 직접 입력하지 않으면 GitLab이 자동으로 생성합니다.

  10. 페이지 만들기를 선택합니다.

로컬에서 위키 페이지 만들기 또는 편집하기

위키는 Git 저장소를 기반으로 하므로, 로컬에서 클론하고 다른 Git 저장소처럼 편집할 수 있습니다. 위키 저장소를 로컬로 클론하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.

  2. 계획 > 위키를 선택합니다.

  3. 위키 작업 ( )을 선택한 다음, 저장소 클론을 선택합니다.

  4. 화면의 지침을 따릅니다.

로컬에서 위키에 추가하는 파일은 사용하려는 마크업 언어에 따라 다음 지원되는 확장자 중 하나를 사용해야 합니다. 지원되지 않는 확장자를 가진 파일은 GitLab에 푸시할 때 표시되지 않습니다:

  • Markdown 확장자: .mdown, .mkd, .mkdn, .md, .markdown.
  • AsciiDoc 확장자: .adoc, .ad, .asciidoc.
  • 기타 마크업 확장자: .textile, .rdoc, .org, .creole, .wiki, .mediawiki, .rst.

페이지 경로의 특수 문자

  • 소개됨 GitLab 16.7에서 프론트 매터 기반 제목이 wiki_front_matter 및 wiki_front_matter_title라는 플래그와 함께. 기본적으로 비활성화되어 있습니다.
  • 기능 플래그 wiki_front_matter 및 wiki_front_matter_title는 GitLab 17.2에서 기본적으로 활성화되어 있습니다.
  • 기능 플래그 wiki_front_matter 및 wiki_front_matter_title는 GitLab 17.3에서 제거되었습니다.

위키 페이지는 Git 저장소의 파일로 저장되며, 기본적으로 페이지의 파일 이름은 제목이기도 합니다. 파일 이름의 특정 문자들은 특별한 의미를 가집니다:

  • 공백은 페이지 저장 시 하이픈으로 변환됩니다.
  • 하이픈(-)은 페이지 표시 시 다시 공백으로 변환됩니다.
  • 슬래시(/)는 경로 구분자로 사용되며, 제목에 표시될 수 없습니다. 제목에 / 문자가 포함된 파일을 만들면 GitLab이 필요한 모든 하위 디렉토리를 생성합니다. 예를 들어, docs/my-page라는 제목은 경로 /wikis/docs/my-page가 있는 위키 페이지를 생성합니다.

이러한 제한을 우회하려면, 페이지 내용 앞에 프론트 매터 블록 내에 위키 페이지의 제목을 저장할 수도 있습니다. 예를 들면:

---
title: 페이지 제목
---

파일 및 디렉토리 이름에 대한 길이 제한

많은 일반 파일 시스템은 파일 및 디렉토리 이름에 대해 255바이트의 제한이 있습니다.

Git 및 GitLab 모두 이러한 제한을 초과하는 경로를 지원합니다.

그러나 파일 시스템이 이러한 제한을 강제하는 경우, 이 제한을 초과하는 파일 이름을 포함한 위키의 로컬 복사를 체크아웃할 수 없습니다.

이 문제를 방지하기 위해 GitLab 웹 인터페이스와 API는 다음과 같은 제한을 시행합니다:

  • 파일 이름은 245바이트(파일 확장자를 위해 10바이트 예약 포함).
  • 디렉토리 이름은 255바이트.

비-ASCII 문자는 1바이트 이상의 공간을 차지합니다.

여전히 이러한 제한을 초과하는 파일을 로컬에 생성할 수 있지만, 여러분의 팀원은 나중에 위키를 로컬로 체크아웃할 수 없을 수 있습니다.

위키 페이지 편집

전제 조건:

  • 최소한 개발자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 편집할 페이지로 이동하고, 다음 중 하나를 수행합니다:
  4. 내용을 편집합니다.
  5. 변경 사항 저장을 선택합니다.

위키 페이지에 대한 저장되지 않은 변경 사항은 우발적인 데이터 손실을 방지하기 위해 로컬 브라우저 저장소에 보존됩니다.

목차 만들기

  • 목차는 GitLab 17.2에서 위키 사이드바에 도입됨.

내용에 제목이 포함된 위키 페이지는 사이드바에 자동으로 목차 섹션을 표시합니다.

페이지 자체에 별도의 목차 섹션을 표시할 수도 있습니다. 위키 페이지의 하위 제목에서 목차를 생성하려면 [_TOC_] 태그를 사용하십시오. 예시는 목차에서 확인할 수 있습니다.

위키 페이지 삭제

전제 조건:

  • 최소한 개발자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 삭제할 페이지로 이동합니다.
  4. 위키 작업( )을 선택한 다음 페이지 삭제를 선택합니다.
  5. 삭제를 확인합니다.

위키 페이지 이동 또는 이름 변경

  • 이동되거나 이름이 변경된 위키 페이지에 대한 리디렉션은 GitLab 17.1에서 도입됨 및 기본적으로 활성화된 wiki_redirection이라는 플래그와 함께 도입되었습니다.
  • 페이지 제목과 경로의 분리는 GitLab 17.2에서 도입됨 및 기본적으로 활성화된 플래그 wiki_front_matter 및 wiki_front_matter_title과 함께 도입되었습니다.
  • GitLab 17.3에서 wiki_redirection, wiki_front_matter 및 wiki_front_matter_title 기능 플래그가 제거되었습니다.

GitLab 17.1 이상에서는 페이지를 이동하거나 이름을 변경할 때 구 페이지에서 새 페이지로 자동으로 리디렉션이 설정됩니다. 리디렉션 목록은 위키 리포지토리의 .gitlab/redirects.yml 파일에 저장됩니다.

전제 조건:

  • 최소한 개발자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 이동하거나 이름을 변경할 페이지로 이동합니다.
  4. 편집을 선택합니다.
  5. 페이지를 이동하려면 경로 필드에 새 경로를 추가합니다. 예를 들어, 회사 아래의 About이라는 위키 페이지가 있고 위키의 루트로 이동하려면 경로를 About에서 /About으로 변경합니다.
  6. 페이지의 이름을 변경하려면 경로를 변경합니다.
  7. 변경 사항 저장을 선택합니다.

위키 페이지 내보내기

위키 페이지를 PDF 파일로 내보낼 수 있습니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 내보내고자 하는 페이지로 이동합니다.
  4. 오른쪽 상단에서 위키 작업 ( )을 선택한 다음 PDF로 인쇄를 선택합니다.

위키 페이지의 PDF가 생성됩니다.

위키 페이지 템플릿

신규 페이지를 만들 때 사용하거나 기존 페이지에 적용할 템플릿을 만들 수 있습니다. 템플릿은 위키 저장소의 templates/ 디렉토리에 저장된 위키 페이지입니다.

템플릿 만들기

전제 조건:

  • 최소한 개발자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 위키 작업 ( )을 선택한 다음 템플릿을 선택합니다.
  4. 새 템플릿을 선택합니다.
  5. 템플릿 제목, 형식 및 내용을 입력합니다. 일반 위키 페이지를 생성하는 것과 같습니다.

특정 형식의 템플릿은 동일한 형식의 페이지에만 적용할 수 있습니다. 예를 들어, Markdown 템플릿은 Markdown 페이지에만 적용됩니다.

템플릿 적용하기

위키 페이지를 생성하거나 편집하는 경우 템플릿을 적용할 수 있습니다.

전제 조건:

  • 최소한 하나의 템플릿을 생성해야 합니다.
  1. 내용 섹션에서 템플릿 선택 드롭다운 목록을 선택합니다.
  2. 목록에서 템플릿을 선택합니다. 페이지에 이미 내용이 있는 경우 경고가 표시되어 기존 내용이 덮어쓰여질 것임을 알려줍니다.
  3. 템플릿 적용을 선택합니다.

위키 페이지의 기록 보기

시간에 따라 위키 페이지의 변경 사항은 위키의 Git 저장소에 기록됩니다. 기록 페이지는 다음을 보여줍니다:

  • 페이지의 수정 사항.
  • 페이지 작성자.
  • 커밋 메시지.
  • 마지막 업데이트.
  • 페이지 버전 열에서 리비전 번호를 선택하여 이전 수정 사항.

위키 페이지의 변경 사항을 보려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 기록을 보려는 페이지로 이동합니다.
  4. 위키 작업 ( )을 선택한 다음 페이지 역사를 선택합니다.

페이지 버전 간 변경 사항 보기

버전이 있는 위키 페이지의 특정 버전에서 이루어진 변경 사항을 볼 수 있습니다. 이는 버전 관리된 차이점 파일 보기와 유사합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 관심 있는 위키 페이지로 이동합니다.
  4. 위키 작업 ( )을 선택한 다음 페이지 역사를 선택하여 모든 페이지 버전을 봅니다.
  5. 관심 있는 버전의 차이점 열에서 커밋 메시지를 선택합니다.

사이드바

위키 페이지는 위키 내 페이지 목록을 포함하는 사이드바를 표시하며,

형제 페이지는 알파벳 순으로 나열된 중첩된 트리로 표시됩니다.

사이드바의 검색 상자를 사용하여 위키에서 제목으로 빠르게 페이지를 찾을 수 있습니다.

성능상의 이유로 사이드바는 최대 5000개의 항목만 표시할 수 있습니다.

모든 페이지의 목록을 보려면 사이드바에서 모든 페이지 보기를 선택하세요.

사이드바 사용자화

사이드바 탐색의 내용을 수동으로 편집할 수 있습니다.

미리 요구 사항:

  • 최소한 개발자 역할이 있어야 합니다.

이 과정은 기본 사이드바 탐색을 완전히 대체하는 _sidebar라는 위키 페이지를 생성합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.
  2. 계획 > 위키를 선택합니다.
  3. 페이지 우측 상단에서 사용자 정의 사이드바 추가( )를 선택합니다.
  4. 완료되면 변경 사항 저장을 선택합니다.

다음은 Markdown으로 포맷된 _sidebar 예제입니다:

### 홈

- [안녕하세요 세계](hello)
- [푸](foo)
- [바](bar)

---

- [사이드바](_sidebar)

프로젝트 위키 활성화 또는 비활성화

위키는 GitLab에서 기본적으로 활성화되어 있습니다. 프로젝트 관리자는 공유 및 권한에서 지침을 따름으로써 프로젝트 위키를 활성화하거나 비활성화할 수 있습니다.

자가 관리 GitLab 설치의 관리자는 추가 위키 설정을 구성할 수 있습니다.

그룹 설정에서 그룹 위키를 비활성화할 수 있습니다.

외부 위키 연결하기

프로젝트의 왼쪽 사이드바에서 외부 위키로의 링크를 추가하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 통합을 선택합니다.
  3. 외부 위키를 선택합니다.
  4. 외부 위키의 URL을 추가합니다.
  5. 선택 사항. 설정 테스트를 선택합니다.
  6. 변경 사항 저장을 선택합니다.

이제 프로젝트의 왼쪽 사이드바에서 외부 위키 옵션을 볼 수 있습니다.

이 통합을 활성화하면 외부 위키에 대한 링크가 내부 위키에 대한 링크를 대체하지 않습니다.

사이드바에서 내부 위키를 숨기려면 프로젝트의 위키를 비활성화하세요.

외부 위키에 대한 링크를 숨기려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 통합을 선택합니다.
  3. 외부 위키를 선택합니다.
  4. 통합 활성화 아래에서 활성 체크박스를 해제합니다.
  5. 변경 사항 저장을 선택합니다.

프로젝트 위키 비활성화

프로젝트의 내부 위키를 비활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 가시성, 프로젝트 기능, 권한을 확장합니다.
  4. 스크롤하여 위키 토글(회색)을 찾아 끕니다.
  5. 변경 사항 저장을 선택합니다.

이제 내부 위키가 비활성화되며, 사용자 및 프로젝트 구성원은 다음을 수행할 수 없습니다:

  • 프로젝트의 사이드바에서 위키 링크를 찾을 수 없습니다.
  • 위키 페이지를 추가, 삭제 또는 편집할 수 없습니다.
  • 어떤 위키 페이지도 볼 수 없습니다.

이전에 추가된 위키 페이지는 나중에 위키를 다시 활성화하려는 경우를 대비하여 보존됩니다.

위키를 다시 활성화하려면 위키를 비활성화하는 과정을 반복하되, 토글을 켭니다(파란색).

리치 텍스트 편집기

  • 이름 변경됨 GitLab 16.2에서 콘텐츠 편집기에서 리치 텍스트 편집기로.

GitLab은 위키에서 GitLab Flavored Markdown을 위한 리치 텍스트 편집 경험을 제공합니다.

지원 사항에는 다음이 포함됩니다:

  • 굵게, 이탤릭체, 블록 인용, 제목 및 인라인 코드를 사용하여 텍스트 형식 지정.
  • 정렬 목록, 비정렬 목록 및 체크리스트 형식 지정.
  • 표 구조 만들기 및 편집.
  • 구문 강조가 있는 코드 블록 삽입 및 형식 지정.
  • Mermaid, PlantUML 및 Kroki 다이어그램 미리보기.

리치 텍스트 편집기 사용

  1. 새 위키 페이지 생성 또는 기존 페이지 편집.
  2. 형식으로 Markdown 선택.
  3. 내용 아래 왼쪽 하단에서 리치 텍스트 편집기로 전환 선택.
  4. 리치 텍스트 편집기에서 제공하는 다양한 형식 옵션을 사용하여 페이지의 내용을 사용자 정의.
  5. 새 페이지의 경우 페이지 생성 선택, 기존 페이지의 경우 변경 사항 저장 선택.

일반 텍스트로 돌아가려면 일반 텍스트 편집기로 전환을 선택합니다.

참고:

GitLab Flavored Markdown 지원

리치 텍스트 편집기에서 모든 GitLab Flavored Markdown 콘텐츠 유형을 지원하는 작업은 진행 중입니다.

CommonMark 및 GitLab Flavored Markdown 지원에 대한 진행 상황을 보려면:

위키 이벤트 추적

GitLab은 위키 생성, 삭제 및 업데이트 이벤트를 추적합니다. 이러한 이벤트는 다음 페이지에 표시됩니다:

위키에 대한 커밋은 저장소 분석에서 계산되지 않습니다.

문제 해결

Apache 리버스 프록시로 페이지 슬러그 렌더링

페이지 슬러그는 ERB::Util.url_encode 메서드를 사용하여 인코딩됩니다.

Apache 리버스 프록시를 사용하는 경우, Apache 구성의 ProxyPass 라인에 nocanon 인수를 추가하여 페이지 슬러그가 올바르게 렌더링되도록 할 수 있습니다.

Rails 콘솔로 프로젝트 위키 다시 만들기

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated
caution
이 작업은 위키의 모든 데이터를 삭제합니다.
caution
데이터를 직접 변경하는 모든 명령은 올바르게 실행되지 않거나 적절한 조건에서 실행되지 않으면 손상을 초래할 수 있습니다. 우리는 인스턴스의 백업이 복원될 준비가 된 테스트 환경에서 실행하는 것을 강력히 권장합니다.

프로젝트 위키의 모든 데이터를 지우고 빈 상태로 다시 만들려면:

  1. Rails 콘솔 세션 시작.

  2. 다음 명령 실행:

    # 프로젝트 경로 입력
p = Project.find_by_full_path('<username-or-group>/<project-name>')

# 이 명령은 파일 시스템에서 위키 프로젝트를 삭제합니다.
p.wiki.repository.remove

# 위키 리포지토리 상태 새로 고침.
p.wiki.repository.expire_exists_cache

위키에서 모든 데이터가 지워졌으며, 위키를 사용할 준비가 되었습니다.

관련 주제