Bitbucket에 아티클 게시

Bitbucket을 한 번 연결하면 모든 Clevera 아티클을 Bitbucket 리포지토리에 Markdown 파일로 게시할 수 있으며, 문서 사이트나 코드 옆의 docs/ 폴더에 바로 사용할 수 있습니다. 이 아티클에서는 연결 방법, 리포지토리 및 폴더 선택, 파일 형태, 업데이트 작동 방식에 대해 다룹니다.

시작하기 전에#

• 플랜: Bitbucket 게시 기능은 Pro 및 Custom 플랜에서 제공됩니다. Free 및 Starter 플랜의 경우 게시 탭에 "도구로 게시하는 기능은 Pro 플랜에 포함되어 있습니다"라는 메시지가 표시됩니다. 플랜 선택을 확인하세요.
• Clevera 내 역할: 워크스페이스 소유자 또는 관리자만 Bitbucket을 연결하거나 연결 해제할 수 있습니다. 연결된 후에는 아티클을 편집할 수 있는 누구나 게시할 수 있습니다.
• Bitbucket Cloud 전용: Clevera는 bitbucket.org에 연결됩니다. Bitbucket Data Center 및 Server는 지원하지 않습니다.
• Bitbucket 액세스 권한: 연결하는 계정은 게시하려는 리포지토리에 기여할 수 있어야 하며, 메인 브랜치에 대한 쓰기 권한이 있어야 합니다.
• 아티클: 동영상이나 녹화본에 속한 아티클을 게시합니다. 먼저 생성하세요. 녹화본을 아티클로 변환을 참조하세요.

게시 시 크레딧은 차감되지 않습니다.

Bitbucket 연결#

1. 연동 열기#

   사이드바에서 워크스페이스 메뉴를 열고 연동을 선택하세요. 사용 가능한 연동 (또는 개발 탭) 아래에서 Bitbucket을 찾아 연결을 클릭하세요.

2. Bitbucket에서 액세스 권한 부여#

   로그인되어 있지 않다면 Bitbucket에 로그인하세요. Bitbucket에서 Clevera에 액세스 권한을 부여하라는 메시지가 표시됩니다:

   Bitbucket 권한	이유
   계정: 읽기	Clevera에 Bitbucket 이름을 표시하기 위해
   리포지토리: 읽기	리포지토리 목록을 가져오고 파일 존재 여부를 확인하기 위해
   리포지토리: 쓰기	Markdown 파일과 이미지를 커밋하기 위해

   액세스 권한 부여를 클릭하세요.

3. 연결 확인#

   연동 페이지로 돌아오면 "Bitbucket이 성공적으로 연결되었습니다"라는 메시지와 함께 Bitbucket 이름이 표시됩니다. Bitbucket은 연결됨 배지와 함께 연결됨 목록으로 이동합니다. 게시하기 전에는 "아직 게시된 항목 없음"으로 표시됩니다.

아티클 게시#

1. 게시 탭 열기#

   에디터에서 공유를 클릭하고 게시 탭을 여세요. 아티클 게시 아래의 게시 준비 완료 섹션에서 Bitbucket 타일을 클릭하세요.

   아티클은 에디터에서 열려 있는 언어로 게시됩니다. 번역본을 게시하려면 먼저 상단 바에서 언어를 전환하세요.

2. 리포지토리 및 폴더 선택#

   게시 위치 아래에서 다음을 선택하세요:

   필드	선택 항목	참고
   리포지토리	파일을 저장할 Bitbucket 리포지토리	Bitbucket 워크스페이스 전반에서 기여 가능한 리포지토리가 최근 업데이트순으로 표시됩니다. 첫 번째 항목이 기본 선택됩니다
   폴더	docs 또는 articles/guides와 같은 경로	"Markdown 파일이 생성될 위치입니다. 리포지토리 루트에 저장하려면 비워두세요." 기본값은 docs입니다. 존재하지 않는 폴더는 새로 생성됩니다

   Clevera는 다음 게시를 위해 선택한 설정을 기억합니다.

   

3. 게시#

   Bitbucket에 게시를 클릭하세요. "Bitbucket에서 기존 복사본을 찾는 중" 메시지가 표시된 후 페이지 작성 중이 나타납니다. 완료되면 "Bitbucket에 게시되었습니다."라는 메시지가 뜹니다. Bitbucket에서 열기를 클릭하여 파일을 확인하세요.

   게시가 진행되는 동안 공유 창을 닫아도 됩니다. 완료되면 알림이 전송됩니다.

파일 저장 위치#

• 브랜치: 리포지토리의 메인 브랜치(보통 main 또는 master). Clevera는 해당 브랜치에 직접 커밋합니다. 풀 리퀘스트를 열지 않으며 다른 브랜치를 선택할 수 없습니다.
• 파일 이름: 제목을 소문자로 변환하고 공백을 하이픈으로 바꾼 뒤 .md로 끝납니다. "Create your first invoice"는 create-your-first-invoice.md이 됩니다. 다른 언어나 악센트가 포함된 제목은 먼저 라틴 문자로 변환됩니다("Créer une facture"는 creer-une-facture.md가 됩니다). 이모지만 포함된 제목처럼 변환할 문자가 없는 경우 짧은 고정 코드(article-와 8자리 문자)가 사용됩니다. 이름은 80자에서 잘립니다.
• 이미지: 아티클의 스크린샷은 같은 폴더 내 assets/<file name>/에 동일한 커밋으로 저장됩니다.
• 커밋 메시지: Add article: <title> 또는 기존 파일 업데이트 시 Update article: <title>.
• 커밋 작성자: 연동을 연결한 Bitbucket 계정.

브랜치 제한#

리포지토리의 메인 브랜치에 브랜치 제한이 있는 경우(예: 풀 리퀘스트를 통해서만 변경 가능, 특정 사용자만 쓰기 가능 등), Clevera의 커밋이 거부될 수 있습니다(예: "이 Bitbucket 리포지토리에 커밋하려면 쓰기 권한이 필요합니다"). 리포지토리 설정 → 브랜치 제한에서 연결된 계정에 쓰기 권한을 추가하거나, 해당 규칙이 없는 리포지토리에 게시하세요.

파일 형태#

Clevera는 Bitbucket 파일 뷰어에서 볼 수 있는 일반 Markdown을 작성하며, 상단에 짧은 프런트 매터 블록이 포함됩니다. Bitbucket은 원시 HTML을 렌더링하지 않으므로 HTML은 포함되지 않습니다.

---
title: "Create your first invoice"
created_at: "2026-10-12T09:30:00+00:00"
updated_at: "2026-10-12T10:05:00+00:00"
source: "Clevera"
---

아티클의 원본 동영상 파일은 파일에 추가되지 않습니다. 아티클 내에 배치된 Clevera 동영상은 동영상의 공유 링크가 켜져 있을 때만 플레이어로 연결되는 링크가 됩니다. 아티클에 동영상 표시를 참조하세요.

이미지#

스크린샷은 파일 옆의 리포지토리에 커밋되며, Markdown은 상대 경로(assets/<file name>/…)로 링크됩니다. Clevera 없이도 계속 작동하며, 비공개 리포지토리에서는 리포지토리의 다른 파일과 동일하게 비공개로 유지됩니다.

아티클에 업로드한 동영상 파일은 커밋되지 않습니다. 일정 시간이 지나면 만료되는 Clevera 링크로 유지되며, 다시 게시하여 갱신할 수 있습니다.

문서 사이트와 함께 사용#

정적 사이트 생성기(MkDocs, Docusaurus, Hugo 등)가 리포지토리에서 문서를 빌드하는 경우, 폴더를 해당 생성기가 읽는 폴더로 지정하세요. 각 게시 작업은 일반 커밋이므로 Bitbucket Pipelines나 다른 빌드 프로세스가 평소대로 실행됩니다. 대부분의 생성기는 프런트 매터에서 title을 읽고 알 수 없는 필드는 무시합니다.

이미 게시한 아티클 업데이트#

게시는 단방향으로만 작동합니다. Clevera에서 수정한 내용은 다시 게시하기 전까지 Clevera에만 유지되며, Bitbucket에서 파일에 변경한 내용은 Clevera로 돌아오지 않습니다.

동일한 리포지토리와 폴더에 게시하면 Clevera가 같은 이름의 파일을 찾아 "이 아티클은 이미 Bitbucket에 있습니다."라고 표시합니다. 보기를 클릭하여 기존 파일을 열고 다음 중 하나를 선택하세요:

Clevera에서 제목을 변경하면 파일 이름도 변경되므로, 게시 시 기존 파일 옆에 새 파일이 생성됩니다. 이전 파일은 직접 삭제하거나 이름을 변경하세요. Clevera는 리포지토리의 파일을 자동으로 삭제하지 않습니다.

Bitbucket 연결 해제#

1. 연동을 열고 Bitbucket 행의 ⋯ 메뉴를 클릭한 뒤 연결 해제를 선택하세요(또는 Bitbucket을 클릭한 후 연결 해제 클릭).
2. 확인하세요. "이제 에디터에서 게시할 수 없습니다. 이미 게시한 콘텐츠는 Bitbucket에 그대로 유지됩니다."

연결을 해제하면 Clevera의 토큰이 삭제됩니다. Bitbucket에서도 Clevera의 액세스 권한을 취소하려면 Bitbucket 개인 설정을 열고 앱 권한으로 이동하여 Clevera의 권한을 취소하세요.

문제 해결#

관련 항목#