위키

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

만약 문서를 저장소에 유지하고 싶지 않지만 코드와 동일한 프로젝트 내에 유지하고 싶다면, GitLab이 제공하는 위키를 사용할 수 있습니다. 각 GitLab 프로젝트의 위키는 별도의 Git 저장소이므로 웹 인터페이스에서 위키 페이지를 생성하거나 로컬에서 Git을 사용하여 위키 페이지를 만들 수 있습니다.

GitLab 위키는 Markdown, RDoc, AsciiDoc 및 Org를 지원합니다. Markdown으로 작성된 위키 페이지는 Markdown 기능을 지원하며, 링크에 대한 위키별 동작도 제공합니다.

위키 페이지에는 또한 사이드바가 표시되며, 사용자 정의할 수도 있습니다.

프로젝트 위키 보기

프로젝트 위키에 액세스하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 위키를 표시하려면:
    • 왼쪽 사이드바에서 Plan > 위키를 선택합니다.
    • 프로젝트의 모든 페이지에서 g + w 위키 키보드 바로 가기를 사용합니다.

만약 Plan > 위키가 프로젝트의 왼쪽 사이드바에 나열되어 있지 않다면, 프로젝트 관리자가 비활성화했을 수 있습니다.

위키의 기본 브랜치 구성

위키 저장소의 기본 브랜치는 GitLab 버전에 따라 다릅니다:

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

모든 GitLab 버전에서 이전에 작성된 위키의 기본 브랜치를 이름을 바꿀 수 있습니다.

위키 홈 페이지 생성

  • wiki_front_matter 및 wiki_front_matter_title이라는 플래그가 기본적으로 활성화된 채로 GitLab 17.2에서 도입됨 (기본적으로 활성화됨).
  • GitLab 17.3에서 wiki_front_matter 및 wiki_front_matter_title 기능 플래그가 제거됨.

위키가 만들어지면 비어 있습니다. 첫 방문 시, 위키를 볼 때 사용자가 보는 홈 페이지를 만들 수 있습니다. 이 페이지는 위키의 홈 페이지로 사용할 특정 경로가 필요합니다. 이를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.
  2. Plan > 위키를 선택합니다.
  3. 첫 번째 페이지를 만들기를 선택합니다.
  4. 옵션. 홈 페이지의 제목을 변경합니다.
  5. GitLab은 이 첫 페이지에 home 경로를 가져야 하므로 이를 위해 경로를 사용합니다. 이 경로의 페이지는 위키의 첫 페이지로 사용됩니다.
  6. 텍스트 스타일을 위한 형식을 선택합니다.
  7. 홈 페이지에 환영 메시지를 추가합니다. 나중에 편집할 수 있습니다.
  8. 커밋 메시지를 추가합니다. 사용자 정의하지 않으면 GitLab이 커밋 메시지를 생성합니다.
  9. 페이지 만들기를 선택합니다.

새 위키 페이지 만들기

  • wiki_front_matter 및 wiki_front_matter_title이라는 플래그가 기본적으로 활성화된 채로 GitLab 17.2에서 도입됨 (기본적으로 활성화됨).
  • GitLab 17.3에서 wiki_front_matter 및 wiki_front_matter_title 기능 플래그가 제거됨.

필수 조건:

  • Developer 역할 이상이어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.
  2. Plan > 위키를 선택합니다.
  3. 이 페이지나 다른 위키 페이지에서 위키 작업 > 새 페이지를 선택합니다.
  4. 콘텐츠 형식을 선택합니다.
  5. 새 페이지의 제목을 추가합니다.
  6. 옵션. 제목에서 페이지 경로 생성을 해제하고 페이지의 경로를 변경합니다. 페이지 경로는 특수 문자를 사용하여 하위 디렉터리 및 형식 지정을 합니다. 또한 길이 제한이 있습니다.
  7. 새 위키 페이지에 콘텐츠를 추가합니다.
  8. 옵션. 파일을 첨부하고 GitLab은 해당 파일을 위키 Git 저장소에 저장합니다.
  9. 커밋 메시지를 추가합니다. 사용자 정의하지 않으면 GitLab이 커밋 메시지를 생성합니다.
  10. 페이지 만들기를 선택합니다.

로컬에서 위키 페이지 만들거나 편집하기

위키는 Git 저장소를 기반으로 하므로 로컬로 복제하여 다른 Git 저장소와 마찬가지로 편집할 수 있습니다. 위키 저장소를 로컬로 복제하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.
  2. Plan > 위키를 선택합니다.
  3. 위키 작업 > 저장소 복제를 선택합니다.
  4. 화면 안내에 따릅니다.

로컬로 추가하는 파일은 지원하는 마크업 언어에 따라 다음과 같은 확장자를 사용해야 하며, 지원되지 않는 확장자의 파일은 GitLab에 푸시할 때 표시되지 않습니다:

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

페이지 경로의 특수 문자

  • GitLab 16.7에서 플래그를 사용하여 개요를 기반으로 한 제목이 도입됨 (기본적으로 비활성화됨).
  • GitLab 17.2에서 wiki_front_matter 및 wiki_front_matter_title 기능 플래그가 기본적으로 활성화됨.
  • GitLab 17.3에서 wiki_front_matter 및 wiki_front_matter_title 기능 플래그가 제거됨.

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

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

이러한 제한을 극복하기 위해 위키 페이지의 제목을 페이지 내용 앞에 있는 개요 블록에 저장할 수도 있습니다. 예를 들면: 

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

파일 및 디렉터리 이름의 길이 제한

많은 일반 파일 시스템은 파일 및 디렉터리 이름에 255바이트의 제한이 있습니다. Git 및 GitLab은 모두 이러한 제한을 초과하는 경로를 지원합니다. 그러나 파일 시스템이 이러한 제한을 강제 적용하는 경우 이름이 이 제한을 초과하는 위키의 로컬 복사본을 확인할 수 없습니다. 이 문제를 방지하려면 GitLab 웹 인터페이스 및 API는 다음과 같은 제한을 적용합니다.

  • 파일 이름의 경우 245바이트(파일의 확장자에 10바이트를 예약)
  • 디렉터리 이름의 경우 255바이트

비 ASCII 문자는 하나 이상의 바이트를 차지합니다.

이러한 제한을 초과하는 파일을 로컬로 생성할 수는 있지만, 동료는 이후에 위키를 로컬에서 확인할 수 없을 수 있습니다.

위키 페이지 편집

전제 조건:

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

위키 페이지의 저장되지 않은 변경 사항은 의도하지 않은 데이터 손실을 방지하기 위해 로컬 브라우저 스토리지에 보관됩니다.

목차 생성

콘텐츠에 제목이 있는 위키 페이지는 사이드바에 자동으로 목차 섹션이 표시됩니다.

또한 페이지 자체에 별도의 목차 섹션을 표시할 수도 있습니다. 위키 페이지의 소제목에서 목차를 생성하려면 [[_TOC_]] 태그를 사용하세요. 예시는 목차를 참조하세요.

위키 페이지 삭제

전제 조건:

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

위키 페이지 이동 또는 이름 바꾸기

  • 페이지 이동 또는 이름 변경에 대한 리디렉션은 GitLab 17.1 이후부터 자동으로 설정됩니다. 새 페이지로 이동하거나 이름을 바꿀 시 리디렉션이 자동으로 설정됩니다. 리디렉션 목록은 위키 저장소의 .gitlab/redirects.yml 파일에 저장됩니다.

전제 조건: - 적어도 개발자 역할이 있어야 합니다.

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

위키 페이지 내보내기

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

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

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

위키 페이지 템플릿

새 페이지를 생성하거나 기존 페이지에 적용할 템플릿을 생성할 수 있습니다. 템플릿은 위키 저장소의 templates/ 디렉터리에 저장되는 위키 페이지입니다.

템플릿 생성

전제 조건:

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

특정 형식의 템플릿은 해당 형식의 페이지에만 적용됩니다. 예를 들어, 마크다운 템플릿은 마크다운 페이지에만 적용됩니다.

템플릿 적용

새 위키 페이지를 만들거나(위키-페이지-생성) 편집할 때 템플릿을 적용할 수 있습니다.

전제 조건:

  • 템플릿을 최소한 하나 이상 생성했어야 합니다.
  1. 콘텐츠 섹션에서 템플릿 선택 드롭다운 목록을 선택합니다.
  2. 목록에서 템플릿을 선택합니다. 페이지에 일부 콘텐츠가 이미 있는 경우 기존 콘텐츠가 덮어쓰여질 것이라는 경고가 표시됩니다.
  3. 템플릿 적용을 선택합니다.

위키 페이지의 이력 보기

시간이 지남에 따른 위키 페이지의 변경 사항은 위키의 Git 저장소에 기록됩니다. 이력 페이지에는 다음이 표시됩니다:

  • 페이지의 리비전.
  • 페이지 작성자.
  • 커밋 메시지.
  • 최종 업데이트.
  • 페이지 버전 열에서 리비전 번호를 선택하여 이전 리비전.

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 확인하려는 페이지로 이동합니다.
  4. Wiki 작업()을 선택한 후 페이지 이력을 선택합니다.

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

위키 페이지의 버전에서 이뤄진 변경 사항을 버전화된 diff 파일 보기와 유사하게 볼 수 있습니다:

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

사이드바

위키 페이지에는 위키의 Git 저장소에 대한 변경 내용을 기록하는 표시가 표시됩니다. - 페이지의 리비전. - 페이지 작성자. - 커밋 메시지. - 최종 업데이트. - 페이지 버전 열에서 리비전 번호를 선택하여 이전 리비전.

위키 페이지의 변경 내용을 확인하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고, 프로젝트나 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 페이지를 찾습니다.
  4. Wiki 작업()을 선택하고 페이지 이력을 선택합니다.

페이지 버전 간 변경 내용 보기

특정 버전의 위키 페이지에서 이뤄진 변경 사항을 볼 수 있습니다. 이는 버전화된 diff 파일 보기와 유사합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고, 프로젝트나 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 관심 있는 위키 페이지로 이동합니다.
  4. Wiki 작업()을 선택하고 페이지 이력을 선택하여 모든 페이지 버전을 볼 수 있습니다.
  5. 관심 있는 버전의 Diff 열의 커밋 메시지를 선택합니다.

사이드바

위키 페이지에는 다음과 같은 측면이 표시되는 사이드바가 표시됩니다: - 위키 페이지를 나타내는 트리 구조로 표시된 페이지 목록. - 알파벳 순서로 나열된 동일 레벨의 페이지.

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

성능상의 이유로, 사이드바에는 5000개의 항목만 표시됩니다. 모든 페이지의 목록을 보려면 사이드바에서 모든 페이지 보기를 선택합니다.

사이드바 사용자 정의하기

수동으로 사이드바 네비게이션의 내용을 편집할 수 있습니다.

요구 사항: - 적어도 개발자 역할이 있어야 합니다.

이 프로세스는 기본 사이드바 네비게이션을 완전히 대체하는 _sidebar라는 위키 페이지를 생성합니다:

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

Markdown으로 형식이 지정된 _sidebar 예시: 

### 홈

- [Hello World](hello)
- [Foo](foo)
- [Bar](bar)

---

- [Sidebar](_sidebar)

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

위키는 GitLab에서 기본적으로 활성화됩니다. 프로젝트 관리자는 공유 및 권한 안내에 따라 프로젝트 위키를 활성화하거나 비활성화할 수 있습니다.

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

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

외부 위키 링크

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

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

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

이 통합을 활성화하면 외부 위키로의 링크가 내부 위키로의 링크를 대체하지 않습니다. 사이드바에서 내부 위키를 숨기려면 프로젝트의 위키를 비활성화하세요.

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

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

프로젝트 위키 비활성화

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

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

내부 위키가 비활성화되었으며 사용자와 프로젝트 구성원은 다음을 할 수 없습니다: - 프로젝트의 사이드바에서 위키 링크를 찾을 수 없습니다. - 위키 페이지를 추가, 삭제 또는 편집할 수 없습니다. - 어떠한 위키 페이지도 볼 수 없습니다.

이미 추가된 위키 페이지는 나중에 다시 활성화하고 싶을 때 보존됩니다. 다시 활성화하려면 위키를 비활성화하는 프로세스를 다시 반복하되 토글을 켜면(파랑)됩니다.

풍부한 텍스트 편집기

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 인수를 추가하여 페이지 슬러그를 올바르게 렌더링되도록 할 수 있습니다.

레일즈 콘솔을 사용하여 프로젝트 위키 다시 만들기

자세한 내용: Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

경고: 이 작업은 위키의 모든 데이터를 삭제합니다.

경고: 데이터를 직접 변경하는 모든 명령은 올바르게 실행되지 않거나 적절한 조건 하에 실행되지 않으면 손상을 줄 수 있습니다. 가능한 경우 백업이 준비된 테스트 환경에서 실행하는 것을 강력히 권장합니다.

프로젝트 위키의 모든 데이터를 지우고 새로 생성하려면:

  1. 레일즈 콘솔 세션 시작.

  2. 아래 명령어를 실행하세요: 

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

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

# 위키 저장소 상태를 새로 고침합니다.
p.wiki.repository.expire_exists_cache

위키의 모든 데이터가 지워지고 위키를 사용할 준비가 되었습니다.

관련 주제