문서를 GitHub 저장소에서 마크다운으로 관리하고 있다면, 저장소를 브레인에 이어 두세요. 저장소에 푸시하면 문서 사이트와 AI 연결이 몇 초 안에 함께 갱신돼요. 깃북(GitBook)의 Git Sync와 같은 방식이에요.
연결하기
- 브레인 관리 → GitHub 탭을 열어요. 새 브레인을 만들 때는 마법사에서 GitHub 저장소에서 만들기를 골라도 돼요.
- 저장소 주소를 넣어요.
https://github.com/회사/문서-저장소처럼요.…/tree/브랜치/폴더주소를 붙이면 브랜치와 문서 폴더까지 한 번에 읽어요. - 접근 권한을 정해요. 방법은 둘이에요(공개 저장소는 둘 다 없이도 돼요).
- GitHub App으로 연결(권장) — 「GitHub에 로그인해 저장소 고르기」를 누르면 조직에 위즈덤베이스 GitHub App을 설치하고 저장소를 고를 수 있어요. 담당자가 바뀌거나 퇴사해도 연결이 유지되고, 토큰처럼 만료되지 않아요. 웹훅도 앱이 알아서 관리해요. (이 서버에 앱이 설정돼 있을 때만 보여요.)
- 개인 액세스 토큰 — GitHub → Settings → Developer settings → Fine-grained tokens에서 이 저장소만 골라 Contents: Read-only 권한으로 만들면 돼요. 웹훅까지 자동으로 등록하려면 Webhooks: Read and write도 켜요.
- 미리보기를 누르면 저장하지 않고 어떤 페이지가 새로 생기고·바뀌고·지워지는지, 본문이 어떻게 달라지는지 먼저 보여 드려요(기존 연결의 「전체 다시 읽기」 전에도 쓸 수 있어요).
- 연결하고 첫 동기화 시작을 누르면 바로 페이지가 만들어져요. 끝난 뒤에도 GitHub 탭에 마지막 동기화에서 바뀐 페이지가 쪽별로 남아요.
저장소가 이렇게 페이지가 돼요
.md파일 하나가 페이지 하나예요. 제목은 프런트매터의title, 없으면 첫# 제목, 그것도 없으면 파일 이름을 써요.- 폴더가 위계가 돼요. 첫 단계 폴더는 그룹(문서 사이트 상단 메뉴), 그 안의 폴더는 섹션, 파일은 페이지예요. 폴더의
README.md는 그 그룹의 첫 페이지이자 이름이 돼요. - 깃북식
SUMMARY.md가 있으면 그 목차를 그대로 따라요. 기본은## 파트가 그룹, 들여쓴 항목이 섹션이에요. 연결 설정의 목차의 ## 제목에서 「하나의 그룹 아래 섹션으로」를 고르면##하나하나가 한 그룹 아래의 섹션이 돼요(들여쓴 항목은 부모 다음에 같은 섹션으로 펼쳐져요). 제목에 섞인<a href=…>같은 깃북 앵커는 걷어 내요..gitbook.yaml의root설정도 읽어요. - 이미 같은 이름의 그룹(상단 메뉴)이 있으면 새로 만들지 않고 이어받아요. 그래서 그 그룹의 주소(예:
/guide)가 그대로 살아요. 이름이 달라서 이어받지 못한 옛 그룹에 숨김 페이지만 남으면, 그 옛 주소는 새 그룹으로 자동 이동(301)해요. - 머리말에
hidden: true를 적은 파일은 숨김 페이지가 돼요(메뉴·검색에는 안 나오고 주소로만 열려요). 목차(SUMMARY.md)에 없어도hidden: true라고 적혀 있으면 가져와요.hidden줄이 없는 파일은 지금 숨김 상태를 건드리지 않아요. - 페이지 안의 상대 링크는 우리 페이지 주소로, 이미지와 첨부 파일은 우리 저장소로 옮겨요. 저장소가 비공개여도 그림이 보여요.
CONTRIBUTING.md,LICENSE.md같은 저장소 관리용 파일과.으로 시작하는 폴더는 건너뛰어요.
페이지 주소를 고정하려면
서비스 코드가 /policies/terms, /pricing 처럼 문서 주소를 직접 링크한다면, 파일 맨 위 머리말에 주소를 적어 두세요.
---
slug: policies/terms
---
# 이용약관
- 머리말
slug가 그 페이지의 주소가 돼요. 한 조각(pricing)도, 여러 조각(admin-help/payments)도 돼요. 제목을 고치거나 폴더를 옮겨도 주소는 그대로예요. - 머리말이 없는 파일은
그룹 주소/제목으로 만들어요(기본). 연결 설정의 페이지 주소 방식에서 「파일 경로」를 고르면 머리말이 없는 파일도 폴더 경로로 만들어요 —guide/install.md→/guide/install, 폴더의README.md→ 폴더 주소(/guide). 머리말slug가 있으면 항상 그쪽이 먼저예요. - 같은 주소를 두 파일이 쓰면 앞선 파일이 이기고, 나머지는 기본 주소로 만든 뒤 동기화 결과에 알려 드려요. 사이트가 먼저 쓰는
files,mcp같은 주소는 못 써요. - 이미 있는 페이지와 이어 붙여요. 가져오기로 만든 페이지처럼 같은 주소의 페이지가 이미 있으면 새로 만들지 않고 그 페이지를 파일과 묶어요(덮어쓰기 전 내용은 수정 기록에 남아요). 브랜치나 문서 폴더를 바꿔도 같은 파일 이름·제목의 페이지는 그대로 이어받아서
-2사본이 생기지 않아요. - 주소가 바뀌면 옛 주소가 자동으로 새 주소로 이동해요(301). 편집기에서 주소를 직접 바꿀 때도 마찬가지예요. 제목 앵커(
#id-2026.07.16처럼 깃북이 만들던 것)도 새 주소에서 그대로 열려요. - 양방향으로 저장할 때 머리말의 다른 값(
slug,icon등)과 파일 첫 줄의# 제목은 원래 글자 그대로 남아요. 위즈덤베이스에서 제목을 직접 바꿨을 때만 새 제목이 들어가요.
푸시하면 자동으로
- GitHub App으로 연결하면 앱이 모든 설치 저장소의 푸시를 알려 줘서 저장소마다 웹훅을 만들 필요가 없어요.
- 토큰을 넣고 연결하면 저장소에 웹훅을 자동으로 등록해요. 푸시가 오면 바뀐 파일만 골라 몇 초 안에 반영돼요.
- 토큰 없이 연결했으면 GitHub 탭에 나오는 Payload URL과 Secret으로 저장소 설정에 웹훅을 직접 추가하면 돼요. 안 추가해도 주기적으로 새 커밋을 확인하니 조금 늦게라도 반영돼요.
- 고쳐진 페이지는 수정 기록이 남아 편집 화면의 기록에서 이전 버전을 볼 수 있어요. 저장소에서 지운 파일의 페이지는 함께 지워져요(설정에서 끌 수 있어요).
양방향으로 쓰려면
기본은 GitHub → 위즈덤베이스 한쪽이에요. 저장소가 정본이라, 동기화되는 페이지를 여기서 고치면 다음 동기화 때 저장소 내용으로 되돌아가요(편집 화면 위에 안내가 보여요).
Git을 안 쓰는 동료도 편집기에서 고쳐야 한다면 양방향을 켜요. GitHub 탭 → 연결 설정에서 토큰에 Contents: Read and write 권한을 주고 「양방향」에 체크하면:
- 동기화되는 페이지를 편집기에서 저장하면 몇 초 안에 그 파일로 커밋돼요. 커밋 작성자에 고친 사람 이름이 남아요. 실제로 고친 블록(문단·표의 행·목록 항목)만 바뀌고, 나머지 줄은 원문 그대로예요(편집기가 표 칸 폭을 다시 맞추거나 빈 줄을 줄이는 서식 차이는 수정으로 치지 않아요). 서식만 달라졌다면 커밋 자체를 만들지 않아요.
- 커밋 메시지는 기본이 「Update 제목 (이름 via Wisdombase)」예요. 편집기 위 칸에 한 줄을 적고 저장하면 그 말이 커밋 제목이 되고, 연결 설정의 커밋 메시지 틀(
{action}{title}{user})로 기본 모양을 바꿀 수도 있어요. - 동기화 그룹 안에서 새로 만든 페이지는 새 파일이 되고(깃북식이면
SUMMARY.md에도 줄이 더해져요), 지운 페이지는 파일이 지워져요. 새로 넣은 이미지는assets/폴더로 올라가요. - 양쪽에서 동시에 고치면 저장소가 이겨요. 페이지는 저장소 내용으로 맞춰지고, 편집한 내용은 편집 화면의 기록에 남아 있어요. 저장한 사람에게는 메일로 알리고, 그 페이지 편집 화면에도 안내가 떠요.
- 페이지를 숨기거나 다시 보이게 하면 파일 머리말의
hidden: true로 올라가요. 페이지 순서 바꾸기·옮기기는 저장소에 올리지 않아요.
보호 브랜치를 쓰는 팀 — 풀 리퀘스트 모드
기준 브랜치(예: main)에 바로 쓸 수 없다면 연결 설정의 저장소에 쓰는 방식을 「작업 브랜치에 커밋하고 풀 리퀘스트 열기」로 바꾸세요.
- 편집기 저장은 작업 브랜치(
wisdombase/edits)에 쌓이고, 풀 리퀘스트 하나로 모여요. 합치면 기준 브랜치에 반영돼요. - 합치기 전까지 그 페이지들은 위즈덤베이스에서 고친 내용이 그대로 유지돼요(동기화가 기준 브랜치 내용으로 덮어쓰지 않아요). 편집 화면에는 「아직 합쳐지지 않았어요」 안내와 풀 리퀘스트 링크가 보여요.
- 합치지 않고 닫으면 기준 브랜치 내용으로 돌아가고, 고친 내용은 수정 기록에 남아요(저장한 사람에게 알려 드려요).
- 토큰이나 앱에 Pull requests: Read and write 권한이 필요해요.
인증이 끊기거나 만료되면
- GitHub 탭에 토큰 발급 계정과 만료일이 보여요. 만료 14일·7일·1일 전과 만료·인증 실패 때 브레인 소유자에게 메일을 보내요. GitHub App으로 연결하면 만료가 없어요.
- 인증이 끊긴 동안 편집기에서 저장하면 「지금은 저장소에 반영되지 않아요」라고 알려 드리고, 그 내용은 보류해 둬요. 새 토큰을 넣거나 앱으로 다시 연결하면 보류된 저장이 저장소에 올라가요. 그 사이 저장소의 같은 파일이 바뀌었다면 저장소가 이기고 편집 내용은 수정 기록에 남아요.
- 연결을 끊을 때 토큰이 이미 만료돼 있으면 저장소에 등록된 웹훅을 지우지 못해요. 안내가 뜨면 저장소 Settings → Webhooks에서 직접 지워 주세요(남아 있어도 이 브레인은 그 알림을 받지 않아요).
알아 두세요
- 저장소 밖에서 직접 만든 페이지는 동기화가 건드리지 않아요. 저장소 문서와 직접 쓴 페이지를 한 브레인에서 섞어 쓸 수 있어요. 「지워진 파일의 페이지도 함께 지우기」를 켜도 동기화로 만든(또는 이어 붙인) 페이지만 지워요. 단, 같은 주소라서 파일과 이어 붙은 페이지는 이때부터 동기화 대상이에요.
- 브레인 하나에는 저장소 하나만 이을 수 있어요. 저장소 안 일부만 쓰려면 문서 폴더를 지정하세요. 폴더 칸을 비우고 저장하면 저장소 전체가 돼요.
- 웹훅 Secret은 화면에서 가려져 있어요. 「보기」를 눌렀을 때만 나타나고, 복사 버튼은 가린 채로도 써요.
- 한 번에 가져오는 마크다운은 2,000개, 저장소는 100MB까지예요. 더 크면 문서 폴더를 지정해 범위를 줄여 주세요.
- 연결을 끊어도 페이지는 그대로 남아요.