위키

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

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

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

위키 페이지에는 사용자 정의할 수 있는 사이드바가 표시됩니다. 이 사이드바에는 위키의 일부 페이지 디렉터리이 표시되며 이는 중첩 트리 형식으로 표시되며 형제 페이지는 알파벳 순서로 나열됩니다. 모든 페이지 디렉터리을 보려면 사이드바에서 모든 페이지 보기를 선택하세요.

위키 사이드바

프로젝트 위키 보기

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

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

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

위키의 기본 브랜치 구성

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

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

어떤 GitLab 버전이든 이전에 생성된 위키의 기본 브랜치 이름을 변경할 수 있습니다.

위키 홈 페이지 생성

위키를 만들면 비어있으며 첫 번째 방문 시 위키를 볼 때 사용자가 보는 홈 페이지를 만들 수 있습니다. 이 페이지에는 위키의 홈 페이지로 사용될 특정 제목이 필요합니다. 이를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > 위키를 선택합니다.
  3. 첫 번째 페이지 만들기를 선택합니다.
  4. GitLab은 이 첫 번째 페이지가 home으로 제목이 지어져 있어야 한다고 요구합니다. 이러한 제목의 페이지는 위키의 첫 페이지로 작동합니다.
  5. 텍스트 스타일을 위해 형식을 선택합니다.
  6. 콘텐츠 섹션에 환영 메시지를 추가합니다. 나중에 항상 편집할 수 있습니다.
  7. 커밋 메시지를 추가합니다. 사용자가 직접 입력하지 않으면 GitLab이 커밋 메시지를 생성합니다.
  8. 페이지 만들기를 선택합니다.

새 위키 페이지 만들기

최소한 Developer 역할을 가진 사용자는 새 위키 페이지를 만들 수 있습니다:

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

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

위키는 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.

페이지 제목의 특수 문자

위키 페이지는 Git 리포지터리의 파일로 저장되므로 특정 문자는 특별한 의미를 가지고 있습니다:

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

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

일부 흔히 사용되는 파일 시스템은 파일 및 디렉터리 이름에 255바이트의 제한을 가지고 있습니다. Git 및 GitLab은 이러한 제한을 초과하는 경로를 지원합니다. 그러나 파일 시스템이 이러한 제한을 적용하는 경우 이러한 제한을 초과하는 파일을 로컬로 체크아웃할 수 없습니다. 이 문제를 방지하기 위해 GitLab 웹 인터페이스 및 API에서 다음과 같은 제한 사항이 적용됩니다:

  • 페이지 제목에 대한 바이트 수는 245바이트(파일 확장자를 위해 10바이트를 예약)입니다.
  • 디렉터리 이름에 대한 바이트 수는 255바이트입니다.

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

이러한 제한을 초과하는 파일을 여전히 로컬로 만들 수 있지만 팀원들이 그 이후에 해당 위키를 로컬로 체크아웃할 수 없을 수 있습니다.

위키 페이지 편집

위키 페이지를 편집하려면 최소한 Developer 역할이 필요합니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > 위키를 선택합니다.
  3. 편집하려는 페이지로 이동한 후 다음 중 하나를 수행합니다:
  4. 콘텐츠를 편집합니다.
  5. 변경 저장를 선택합니다.

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

목차 생성

위키 페이지의 하위 제목에서 목차를 생성하려면 [[_TOC_]] 태그를 사용하세요. 예시는 목차를 참조하세요.

위키 페이지 삭제

사전 요구 사항:

  • Developer 역할 이상이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > 위키를 선택합니다.
  3. 삭제하려는 페이지로 이동합니다.
  4. 편집 아이콘()을 선택합니다.
  5. 페이지 삭제를 선택합니다.
  6. 삭제를 확인합니다.

위키 페이지 이동

전제 조건:

  • 적어도 개발자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 이동하려는 페이지로 이동합니다.
  4. 편집 아이콘()을 선택합니다.
  5. 새 경로를 제목 필드에 추가합니다. 예를 들어, company 아래에 about라는 위키 페이지가 있고 이를 위키 루트로 이동하려면 제목을 about에서 /about로 변경합니다.
  6. 변경 사항 저장을 선택합니다.

위키 페이지 내보내기

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

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

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

위키 페이지 템플릿

새 페이지를 만들거나 기존 페이지에 적용할 템플릿을 만들 수 있습니다. 템플릿은 위키 리포지터리의 templates/ 디렉터리에 저장된 위키 페이지입니다.

템플릿 만들기

전제 조건:

  • 적어도 개발자 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 오른쪽 사이드바에서 Templates를 선택합니다.
  4. 새로 만들기를 선택합니다.
  5. 템플릿 제목, 형식 및 내용을 입력하십시오. 일반 위키 페이지를 만드는 것과 마찬가지로 입력합니다.

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

템플릿 적용

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

전제 조건:

  1. 내용 섹션에서 템플릿 선택 드롭다운 디렉터리을 선택합니다.
  2. 디렉터리에서 템플릿을 선택합니다. 페이지에 이미 일부 내용이 있는 경우 기존 내용이 덮어쓰여질 것이라는 경고가 표시됩니다.
  3. 템플릿 적용을 선택합니다.

위키 페이지의 이력 보기

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

위키 페이지 이력

  • 페이지의 리비전(Git 커밋 SHA).
  • 페이지 저자.
  • 커밋 메시지.
  • 마지막 업데이트.
  • 페이지 버전 열에서 리비전 번호를 선택하여 이전 리비전을 볼 수 있습니다.

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

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

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

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 관심 있는 위키 페이지로 이동합니다.
  4. 페이지 이력을 선택하여 모든 페이지 버전을 볼 수 있습니다.

  5. 관심 있는 버전의 변경 열에서 커밋 메시지를 선택합니다.

    위키 페이지 변경 사항

위키 이벤트 추적

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

위키에 대한 커밋은 리포지터리 분석에서 계산되지 않습니다.

사이드바 사용자 정의

사이드바 내용을 매뉴얼으로 편집할 수 있습니다.

전제 조건:

  • 적어도 개발자 역할이 있어야 합니다.

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 페이지의 오른쪽 상단에서 사이드바 편집을 선택합니다.
  4. 완료하면 변경 사항 저장을 선택합니다.

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

### [홈](home)

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

---

- [사이드바](_sidebar)

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

GitLab에서 프로젝트 위키는 기본적으로 활성화되어 있습니다. 프로젝트 관리자는 공유 및 권한에서 프로젝트 위키를 활성화 또는 비활성화할 수 있습니다.

Self-Managed형 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에 대한 WYSIWYG 편집 환경을 제공합니다.

지원 사항은 다음과 같습니다:

  • 볼드체, 이탤릭체, 블록 인용, 헤딩, 인라인 코드 등을 사용한 텍스트 서식 지정.
  • 순서가 있는 디렉터리, 순서가 없는 디렉터리, 체크리스트의 서식 지정.
  • 테이블 구조의 생성 및 편집.
  • 구문 강조가 포함된 코드 블록의 삽입 및 서식 지정.
  • Mermaid, PlantUML 및 Kroki 다이어그램 미리보기 (GitLab 15.2에서 소개).
  • HTML 주석의 생성 및 편집 (GitLab 15.7에서 소개).

풍부한 텍스트 편집기 사용하기

  1. 새 위키 페이지 생성 또는 기존 페이지 편집.
  2. 형식으로 Markdown을 선택합니다.
  3. 콘텐츠 위에서 풍부한 텍스트 편집을 선택합니다.
  4. 풍부한 텍스트 편집기에서 제공되는 다양한 서식 옵션을 사용하여 페이지 내용을 사용자 정의합니다.
  5. 새 페이지의 경우 페이지 생성, 기존 페이지의 경우 변경 사항 저장을 선택합니다.

풍부한 텍스트 편집 모드는 원시 소스 편집으로 전환할 때까지 기본값으로 유지됩니다.

이전 편집기로 전환

  1. 풍부한 텍스트 편집기에서 페이지를 편집 중인 경우, 콘텐츠로 스크롤합니다.
  2. 소스 편집을 선택합니다.

GitLab Flavored Markdown 지원

풍부한 텍스트 편집기에서 모든 GitLab Flavored Markdown 콘텐츠 유형을 지원하는 작업이 진행 중입니다. CommonMark 및 GitLab Flavored Markdown 지원의 진행 상황에 대한 자세한 내용은 다음을 참조하십시오:

관련 주제

문제 해결

아파치 역방향 프록시에서 페이지 슬러그 렌더링

페이지 슬러그는 ERB::Util.url_encode 메소드를 사용하여 인코드됩니다. 아파치 역방향 프록시를 사용하는 경우, 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

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