위키

Tier: Free, Premium, Ultimate Offering: GitLab.com, 자체 호스팅, GitLab Dedicated

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

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

GitLab 13.5 및 이후에서 위키 페이지에는 사이드바가 표시되며, 이를 사용자 정의할 수 있습니다. 이 사이드바에는 위키의 일부 페이지 목록이 포함되어 있고, 계층 구조 트리로 표시되며 알파벳순으로 동일 계층 페이지가 나란히 나열됩니다. 모든 페이지 목록을 보려면 사이드바에서 모든 페이지 보기를 선택하세요:

위키 사이드바

프로젝트 위키 보기

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

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

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

위키의 기본 브랜치 구성

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

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

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

위키 홈 페이지 생성

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

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

새 위키 페이지 만들기

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

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

로컬에서 위키 페이지 생성 또는 편집

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  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 문자는 1바이트보다 많은 공간을 차지합니다.

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

위키 페이지 편집

위키 페이지를 편집하려면 최소한의 개발자 역할이 필요합니다.

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  3. 편집하려는 페이지로 이동하고 다음을 수행합니다.
  4. 내용을 편집합니다.
  5. 변경 사항 저장을 선택합니다.

위키 페이지의 저장되지 않은 변경 사항은 로컬 브라우저 저장소에 유지되어 무작위 데이터 손실을 방지합니다.

목차 생성

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

위키 페이지 삭제

전제 조건:

  • 최소한의 개발자 역할이 필요합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. Plan > Wiki를 선택합니다.
  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. 오른쪽 사이드바에서 템플릿을 선택합니다.
  4. 새 템플릿을 선택합니다.
  5. 일반 위키 페이지를 만드는 것처럼 템플릿 제목, 형식, 내용을 입력합니다.

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

템플릿 적용

새 위키 페이지 생성 또는 편집할 때 템플릿을 적용할 수 있습니다.

필수 조건:

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

위키 페이지 이력 보기

위키 페이지의 변경사항은 위키의 Git 리포지토리에 기록됩니다. 이력 페이지는 다음을 보여줍니다:

위키 페이지 이력

  • 페이지의 버전(Git 커밋 SHA).
  • 페이지 작성자.
  • 커밋 메시지.
  • 최종 업데이트.
  • 페이지 버전 열에서 버전 번호를 선택하여 이전 버전을 확인할 수 있습니다.

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

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

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

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

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

  5. 변경 열의 커밋 메시지를 선택합니다.

    위키 페이지 변경사항

위키 이벤트 추적

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

위키에 커밋은 리포지토리 분석에 포함되지 않습니다.

사이드바 사용자화

  • GitLab 13.8에서 도입되었습니다. 사이드바는 사이드바 편집 버튼을 선택하여 사용자화할 수 있습니다.

필수 조건:

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

이 과정은 _sidebar라는 위키 페이지를 만들어 기본 사이드바 내비게이션을 완전히 대체합니다.

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

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

### [홈](home)

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

---

- [사이드바](_sidebar)

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

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

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

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

외부 위키 링크

프로젝트의 왼쪽 사이드바에 외부 위키 링크를 추가하려면 다음을 수행하세요:

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

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

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

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

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

프로젝트의 위키 비활성화

프로젝트의 내부 위키를 비활성화하려면 다음을 수행하세요:

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

내부 위키가 이제 비활성화되었으며 사용자 및 프로젝트 구성원은:

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

이전에 추가된 위키 페이지는 위키를 다시 활성화하고 싶은 경우를 대비하여 보존됩니다. 활성화하려면 위키를 비활성화하는 프로세스를 반복하되 토글을 켭니다(파랑).

리치 텍스트 편집기

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 지원에 대한 진행 상황은 다음을 참조하세요:

관련 주제

문제 해결

아파치 Reverse Proxy에서 페이지 슬러그 렌더링

GitLab 14.9 이후로 페이지 슬러그는 이제 ERB::Util.url_encode 메소드를 사용하여 인코딩됩니다. 아파치 Reverse Proxy를 사용하는 경우, 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

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