GitBook에 아티클 게시하기
개인 액세스 키로 GitBook을 연결하고 Clevera 아티클을 GitBook 스페이스의 페이지로 게시하세요. 키 생성 방법, 사이트 선택, 힌트·단계·탭 변환 방식, 업데이트 시 동작 및 일반적인 오류에 대해 알아봅니다.
Clevera 아티클을 GitBook 스페이스의 페이지로 게시합니다. GitBook은 로그인 대신 개인 액세스 키로 연결되며, 페이지는 선택한 스페이스의 최상위 수준에 나타납니다.
시작하기 전에
- Clevera: 워크스페이스가 Pro 또는 사용자 지정 플랜이어야 하며, GitBook을 연결하려면 소유자 또는 관리자 권한이 필요합니다. 연결 후에는 아티클을 편집할 수 있는 누구나 게시할 수 있습니다. 다른 도구에 아티클 게시하기를 참조하세요.
- GitBook: 모든 플랜에서 가능합니다. 키는 해당 키를 생성한 GitBook 사용자의 권한으로 작동하므로, 게시하려는 스페이스에 대한 편집 권한이 필요합니다.
- 아티클: 먼저 아티클을 생성하세요. 게시하면 아티클만 전송됩니다. 동영상을 포함하려면 아티클 내부에 배치하세요. 아티클에 동영상 표시하기를 참조하세요.
GitBook 액세스 키 생성
- GitBook에서 계정 설정을 열고 Developer로 이동합니다(
app.gitbook.com/account/developer). - 새 개인 액세스 토큰을 생성하고 "Clevera"와 같은 이름을 지정한 뒤 복사합니다. GitBook은 이 키를 한 번만 보여줍니다.
GitBook 연결
연결 창 열기
Clevera 사이드바에서 워크스페이스 이름을 클릭하고 연동을 선택한 다음, GitBook을 찾아 연결을 클릭합니다. GitBook 연결 창에 "키를 붙여넣으세요. 저장하기 전에 먼저 확인합니다."라는 메시지가 표시되며, Developer 페이지로 이동하는 Open GitBook 링크가 있습니다.
키 붙여넣기 및 확인
액세스 키에 키를 붙여넣고 키 확인을 클릭합니다. GitBook이 수락하면 "키가 확인되었습니다."라는 메시지가 표시됩니다.
사이트 선택
게시할 사이트 아래에 Clevera가 문서 사이트(또는 스페이스) 목록을 표시하고 모두 선택합니다. 목록을 열어 원하지 않는 사이트의 체크를 해제한 뒤(예: "3개 중 2개 선택됨"), 연결을 클릭합니다. "GitBook이 연결되었습니다."라는 메시지가 표시됩니다.
Clevera는 저장하기 전에 키를 확인합니다.
GitBook 계정에 스페이스가 전혀 없는 경우, Clevera는 첫 번째 조직에 "Clevera"라는 이름의 스페이스를 생성하여 바로 게시할 수 있도록 합니다.
키는 Clevera 측에서 만료되지 않습니다. 키나 사이트를 변경하려면 GitBook 연결의 ⋯ 메뉴를 열고 다시 연결을 선택하여 동일한 창을 진행하세요. 새 키와 선택 사항이 이전 내용을 대체합니다.
GitBook에 아티클 게시
게시 탭 열기
에디터에서 공유 → 게시를 클릭하고 게시 준비 완료 아래의 GitBook 타일을 클릭합니다.
스페이스 선택
게시 위치 아래의 목록에는 선택한 사이트의 기반이 되는 스페이스가 아이콘과 함께 표시됩니다.
게시
GitBook에 게시를 클릭합니다. Clevera는 먼저 기존 복사본이 있는지 확인합니다. 동일한 제목의 페이지가 이미 스페이스에 있는 경우 수행할 작업을 선택하세요(게시한 페이지 업데이트하기 참조). 완료되면 "GitBook에 게시되었습니다."라는 메시지가 표시됩니다. GitBook에서 열기를 클릭하여 페이지를 확인하세요.
게시가 진행되는 동안 공유 창을 닫아도 됩니다. 완료되면 알림이 표시됩니다.
페이지는 스페이스의 최상위 수준에 추가되며, 주소는 제목에서 파생됩니다. 예: "Set up billing"은 /set-up-billing이 됩니다. 다른 문자로 된 제목이나 악센트가 있는 제목은 먼저 라틴 문자로 표기되며, 변환할 내용이 없는 제목은 짧은 고정 코드가 부여됩니다. 나중에 GitBook에서 페이지를 이동하거나 이름을 변경할 수 있습니다.
GitBook에서 페이지가 표시되는 방식
페이지 제목은 아티클 제목과 동일합니다. 페이지에는 아티클만 포함되며, 아티클의 원본 동영상은 추가되지 않습니다.
| Clevera | GitBook |
|---|---|
| 제목, 단락 | 제목 및 텍스트 |
| 굵게, 기울임꼴, 취소선, 인라인 코드, 링크 | 유지됨 |
| 강조, 위첨자, 아래첨자 | 유지됨 |
| 글머리 기호 및 번호 매기기 목록, 체크리스트 | 목록 및 작업 목록 |
| 인용구 | 인용구 |
| 코드 블록 | 언어 및 코드 제목이 포함된 코드 블록 |
| 구분선 | 구분선 |
| 표 | 각 셀의 텍스트가 포함된 표 |
| 콜아웃 | 힌트 블록: info → Info, note → Info, tip → Success, success → Success, warning → Warning, danger → Danger |
| 번호 매기기 단계 | GitBook 스텝퍼(단계당 한 단계) |
| 탭 | GitBook 탭 |
| 접기 섹션 | 확장 가능한 블록 |
| 카드 | 설명이 포함된 링크 목록(카드 아이콘은 제외됨) |
| 수식 | GitBook 수식 |
| 스크린샷 | 캡션과 함께 스페이스에 업로드된 이미지 |
| 아티클 내 동영상 및 임베드 | 임베드 블록. Clevera 동영상은 해당 동영상의 공유 링크가 켜져 있을 때만 포함됩니다. |
스크린샷은 파일로 스페이스에 업로드되므로 Clevera에서 아티클을 삭제해도 계속 작동합니다. 아티클에 업로드된 동영상 파일은 일정 시간이 지나면 만료되는 Clevera 링크로 유지되므로, 다시 게시하여 갱신하세요.
게시한 페이지 업데이트하기
게시는 단방향으로만 진행됩니다. Clevera에서 아티클을 편집해도 GitBook 페이지는 업데이트되지 않으며, GitBook에서 변경한 내용은 Clevera로 돌아오지 않습니다. 아티클을 편집한 후 동일한 스페이스에 다시 게시하세요. Clevera는 동일한 제목(대소문자 구분 없음)이나 동일한 주소를 가진 페이지를 찾고 "이 아티클은 이미 GitBook에 있습니다."라고 표시합니다.
- 기존 아티클 업데이트는 해당 페이지의 콘텐츠와 제목을 덮어씁니다. 주소는 동일하게 유지됩니다. 그동안 GitBook에서 변경한 내용은 덮어쓰여지지만, GitBook 기록을 통해 복구할 수 있습니다. GitBook에서 업데이트를 클릭하세요.
- 새 아티클 생성은 입력한 새 제목(Clevera가 "Set up billing (2)"와 같이 제안함)으로 고유 주소를 가진 두 번째 페이지를 추가합니다. 새 아티클 생성을 클릭하세요.
연결 해제 및 액세스 권한 취소
- Clevera에서 연동을 열고 GitBook을 클릭한 다음 연결 해제를 선택하고 확인합니다. 이미 게시한 페이지는 GitBook에 그대로 남습니다.
- GitBook의 Developer 페이지에서 액세스 키를 삭제하여 다시 사용할 수 없도록 합니다.
문제 해결
| 표시되는 메시지 | 해결 방법 |
|---|---|
| "키를 먼저 붙여넣으세요." | 키 필드가 비어 있습니다. |
| "유효하지 않은 GitBook 액세스 키입니다. 확인 후 다시 시도하세요." | 키가 잘못되었거나 삭제되었습니다. 새로 생성하여 붙여넣으세요. |
| "GitBook 액세스 키 확인에 실패했습니다." 또는 "키를 확인할 수 없습니다. 다시 시도하세요." | GitBook이 응답하지 않았습니다. 잠시 후 다시 시도하세요. |
| "최소 하나의 사이트를 선택하세요." | 연결하기 전에 최소 하나의 사이트를 체크하세요. |
| "GitBook 스페이스나 문서 사이트를 찾을 수 없으며 자동으로 생성할 수 없습니다. GitBook에서 스페이스를 생성한 후 다시 시도하세요." | GitBook에서 스페이스를 생성한 후 다시 연결하세요. |
| "GitBook 연결에 실패했습니다. 액세스 키를 확인하세요." | 키를 확인하고 다시 연결하세요. |
| "GitBook 스페이스를 불러올 수 없습니다. 다시 시도하세요." | 다시 시도를 클릭하세요. 반복되면 GitBook을 다시 연결하세요. |
| "게시할 스페이스를 선택하세요." | 먼저 스페이스를 선택하세요. |
| 목록에 스페이스가 없음 | 선택한 사이트에 포함되지 않았거나 키 사용자가 볼 수 없는 스페이스입니다. 다시 연결하여 사이트를 선택하세요. |
| "GitBook이 페이지 콘텐츠를 거부했습니다" 또는 "GitBook이 변경 요청을 병합할 수 없습니다" (GitBook의 이유 포함) | 키 사용자가 해당 스페이스를 편집할 수 없거나 GitBook이 변경을 거부한 경우입니다. GitBook에서 권한을 확인한 후 다시 시도를 클릭하세요. |
| "액세스 키를 찾을 수 없습니다. GitBook을 다시 연결하세요." | 키를 사용하여 GitBook을 다시 연결하세요. |
| "아티클 콘텐츠가 비어 있거나 유효하지 않습니다." | 아티클에 아직 콘텐츠가 없습니다. 열어서 확인한 후 게시하세요. |
| "대체할 페이지를 GitBook에서 찾을 수 없습니다. 이동되었거나 삭제되었을 수 있습니다." | 대신 새 아티클 생성을 선택하세요. |
| "GitBook에 게시하지 못했습니다. 다시 시도하세요." 또는 "GitBook에서 페이지를 업데이트하지 못했습니다. 다시 시도하세요." | 다시 시도를 클릭하세요. 계속 실패하면 새 키로 다시 연결하세요. |