위키

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 14.9에서 페이지 로딩이 비동기로 변경되었습니다.
  • GitLab 14.9에서 페이지 슬러그 인코딩 방법이 ERB::Util.url_encode로 변경되었습니다.

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

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

GitLab 13.5 및 이후에는 위키 페이지에 사이드바가 표시되며, 이를 사용자 정의할 수 있습니다. 이 사이드바에는 위키의 일부 페이지가 표시되며, 이는 상위 페이지가 알파벳 순서로 표시되는 중첩된 트리로 표시됩니다. 모든 페이지 디렉터리을 보려면 사이드바에서 모든 페이지 보기를 선택하십시오:

위키 사이드바

프로젝트 위키 보기

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

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

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

위키의 기본 브랜치 구성

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

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

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

위키 홈 페이지 생성

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

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

새 위키 페이지 생성

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

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

위키 페이지 기록

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

위키 페이지의 변경 사항을 보려면 다음을 수행합니다:

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

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

특정 버전의 위키 페이지에서 만들어진 변경 사항을 보여주는 경우, 버전화된 파일 보기와 유사한 방식으로 변경 사항을 볼 수 있습니다:

  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. 내용 위에 리치 텍스트 편집을 선택합니다.
  3. 리치 텍스트 편집기에서 제공되는 다양한 서식 옵션을 사용하여 페이지의 내용을 사용자화합니다.
  4. 새 페이지를 만들려면 페이지 생성, 기존 페이지를 편집하려면 변경 사항 저장을 선택합니다.

리치 텍스트 편집 모드는 원시 소스 편집으로 돌아갈 때까지 기본 설정으로 유지됩니다.

이전 편집기로 전환

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

GitLab Flavored Markdown 지원

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

관련 주제

문제 해결

Apache Reverse 프록시에서 페이지 슬러그 렌더링

GitLab 14.9 이후, 페이지 슬러그는 이제 ERB::Util.url_encode 방법을 사용하여 인코딩됩니다. Apache Reverse 프록시를 사용하는 경우, 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

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