garden-to-wikidocs

name	garden-to-wikidocs
description	정한의 디지털 가든(Quartz/Hugo MD, ~/repos/gh/notes/content)을 위키독스 깃허브 연동 책(book_id 20676)으로 내보낼 때 사용한다. 폴더 미러 3단계 파이프라인(build 씨뿌리기 → recover 회수 → relink 링크 실화). 가든 원본은 절대 수정하지 않고, denote-id 파일명·날짜접두어 제목·callout·relref·citeproc·이미지·회사신원 난독화를 처리한다. push 하면 웹훅이 위키독스를 동기화한다.

가든 → 위키독스 깃허브 연동 책 내보내기 (v2)

이 리포(junghan0611/garden2wikidocs)는 위키독스 책 20676 "Junghanacs's Digital Garden" 과 깃허브 연동돼 있다. git push → 웹훅 → 위키독스 동기화.

정본·발견면 계약

cross-repo 정책 SSOT는 garden의 docs/WIKIDOCS_MIRROR.md (로컬: /home/junghan/repos/gh/notes/docs/WIKIDOCS_MIRROR.md)다.

• garden은 canonical/latest/authored source다.
• WikiDocs는 한국어 검색과 읽기를 위한 discovery mirror다.
• garden2wikidocs는 garden 원본을 바꾸지 않는 read-only translation harness다.

이 리포는 미러 생성물·page_id·WikiDocs URL의 기준 경로이며, 위키독스 웹 UI 편집은 기준 경로가 아니다. source authority와 publication ordering은 위 정책 SSOT가 소유한다. 구현 세부는 이 skill이 소유하지만 그 정책을 독자적으로 재정의하지 않는다. 가든 전체를 폴더 단위로 올려 위키독스 안에서 자기완결적으로 순회하게 하는 것이 목표다.

3단계 파이프라인

[1] build.py   씨뿌리기 — 가든 폴더 → pages/<folder>/<denote-id>.md + TOC.md + mapping.json
               + BUILD-MANIFEST.json, content/index.md → README.md(위키독스 책 '대문'),
               폴더·autholog 표지 → `## 제목` + 날짜·태그 + description + 읽기 링크의
               AEO recent-first 집합면. garden frontmatter의 title/description/date/lastmod를
               읽고, 각 본문 페이지에 abstract-first `원본·최신본` block + <!-- gid:ID --> 앵커를 둔다.
               내부 relref 는 가든 절대URL, provenance source URL은 relink에서 보호.
               기존 mapping의 page_id/url은 동일 Denote ID에 승계하되, 직전 판 TOC 밖이던
               항목이 발행면에 새로 들어오면 죽은 id라 승계하지 않는다. 회수 이력이 있는데
               직전 판 TOC를 못 읽으면 판정 불가라 생성물을 쓰기 전에 멈춘다.
[2] recover.py 회수 — 최초 push 또는 새 페이지 동기화 후 book get 으로 gid<->page_id 및
               collection marker<->standalone 표지 page_id 회수
[3] relink.py  링크 실화 — 현재 TOC 발행면 페이지 + README 안에서, 가든 URL 중
               발행면에 있는 page_id 만 wikidocs.net/<page_id> 로 재작성(나머지는
               가든 URL 유지, 하이브리드). 발행면 밖 파일은 아예 열지 않는다.
               `/tags/autholog/` 링크도 회수된 어쏠로그 집합 표지로 실화한다.
[검증] audit.py  품질 게이트 — TOC·mapping·gid·page_id·source metadata/provenance·
               AEO 표지 exact match + `##`/읽기 링크 수·순서·uniqueness/completeness·
               abstract ordering·미처리 relref·원본/미러 헤딩 보존
[상태] status.py push 후 웹훅 반영 진척 — book get 라이브 본문 vs 로컬 pages/ 대조로
               gid 페이지와 collection marker의 synced/pending/missing 카운트.
               대량 push 는 한 번에 안 도는 일이 잦다.

pages/x.md 같은 상대 링크는 위키독스에서 작동하지 않는다(메인으로 튕김). 페이지 간 링크는 반드시 https://wikidocs.net/<page_id> 절대 URL이어야 하고, page_id 는 페이지 생성 후에만 생기므로 3단계가 구조적으로 불가피하다.

실행 — audit 이전 push 금지

push 한 번이 약 20분짜리 전체 WikiDocs webhook을 촉발한다. build 직후 push하지 말고, 반드시 relink와 audit을 먼저 통과한다.

정상 갱신(코어 발행면 — 500 상한 아래)

python3 .claude/skills/garden-to-wikidocs/scripts/build.py \
  --folders journal,meta,bib,notes,botlog --core
python3 .claude/skills/garden-to-wikidocs/scripts/relink.py         # 코어 내부 순회
python3 .claude/skills/garden-to-wikidocs/scripts/audit.py --core
python3 -m unittest discover -s tests -q                         # gate
# gitleaks dir . --no-banner --redact                           # optional gate
# 위 gate 뒤 GLG 승인 시에만 commit/push
# git add -A && git commit -m "..." && git push origin main
WIKIDOCS_TOKEN="$(pass personal/token/wikidocs/junghanacs)" \
  python3 .claude/skills/garden-to-wikidocs/scripts/status.py --book-id 20676 --list

build 는 pages/ 를 통째로 다시 쓰므로 relink 결과가 매번 지워진다. build 를 돌렸으면 relink 도 반드시 다시 돌린다. audit 은 relink 뒤에 돌려야 발행면 밖 page_id 참조까지 검사한다.

신규 page_id가 있는 갱신

새 노트만이 아니다. 가든에서 기존 노트에 autholog 태그를 붙이면 그 노트가 발행면에 새로 들어오면서 같은 2단계가 필요해진다. 어쏠로그 회수는 계속 도는 작업이라 이 경우가 정상 갱신보다 흔하다. build 가 [warn] 발행면 page_id 미회수 N개 를 찍으면 이 절차다.

python3 .claude/skills/garden-to-wikidocs/scripts/build.py \
  --folders journal,meta,bib,notes,botlog --core
python3 .claude/skills/garden-to-wikidocs/scripts/relink.py
python3 .claude/skills/garden-to-wikidocs/scripts/audit.py \
  --core --allow-missing-page-ids
# GLG 승인 후 1차 commit/push → status.py 로 생성 동기화 확인
WIKIDOCS_TOKEN="$(pass personal/token/wikidocs/junghanacs)" \
  python3 .claude/skills/garden-to-wikidocs/scripts/recover.py --book-id 20676
python3 .claude/skills/garden-to-wikidocs/scripts/build.py \
  --folders journal,meta,bib,notes,botlog --core
python3 .claude/skills/garden-to-wikidocs/scripts/relink.py
python3 .claude/skills/garden-to-wikidocs/scripts/audit.py --core
python3 -m unittest discover -s tests -q
# GLG 승인 후 2차 commit/push → status.py --list 로 pending 0 확인

--core 발행면에서는 새 표지 하나를 올리는 데도 이 2단계가 필요하다. 회수 뒤 build 를 다시 돌려야 회수한 page_id 가 표지 목록에 반영된다.

진척이 멈춰 pending이 남으면 위키독스 책 수정 > 깃허브 > 지금 동기화를 수동 재트리거한다.

• build.py --folders journal,meta,bib,notes,botlog 처럼 쉼표로 여러 폴더 동시 처리. 알려진 챕터는 입력 순서와 무관하게 1 저널·2 메타·3 참고문헌·4 노트·5 봇로그로 정렬.
• --core 는 TOC 등록을 발행 코어(autholog 태그 ∪ botlog 폴더)로 제한한다. 500 상한 대응이며 pages/·mapping.json 은 가든 전량을 그대로 만든다. 상한을 넘기면 build 가 생성물을 쓰기 전에 실패한다. 코어에서 저널을 뺀 이유는 저널만이 시간축으로 계속 늘어나는 유일한 발행 증가원이기 때문이다(나머지는 새 노트 생성이 아니라 수선으로 자란다).
• --garden-links 는 표지·집합면의 링크를 전부 가든 원본으로 낸다. 기본값이 아니다. 코어에 담은 노트끼리는 위키독스 안에서 순회해야 읽기가 끊기지 않으므로, 평소에는 이 옵션 없이 build 하고 relink.py 를 돌린다(2026-07 실측: 발행면 249개 안에서 내부 순회율 33%, 나머지는 코어 밖 노트라 가든으로 나가는 게 맞다). 발행면을 크게 갈아엎는 전환기에 링크를 한 곳으로 몰고 싶을 때만 켜는 안전판이다. audit 에는 build 와 같은 옵션을 그대로 넘긴다.
• --garden 기본 ~/repos/gh/notes, --out 기본은 README.md 있는 리포 루트.
• build는 garden content/·change-text.sh가 dirty/untracked면 생성물 쓰기 전에 실패한다. canonical garden commit 뒤에만 미러를 생성한다.
• 의존성 0(Python 표준 라이브러리). 토큰은 pass personal/token/wikidocs/junghanacs.

실측으로 확정된 불변식 (깨지 말 것 — 실험으로 검증됨)

• 책 한 권의 상한은 TOC.md 등록 페이지 500개다. 넘으면 웹훅이 동기화를 통째로 거부한다(GitHub 동기화 실패: TOC.md에 2244개의 페이지가 등록되어 있습니다. 책의 페이지는 최대 500개까지만 가능합니다.). 커밋 델타 크기와 무관하게 매번 걸리므로 TOC 를 줄이는 것 외에 우회로가 없다. 2026-07-18 까지는 없던 규칙이 사후 도입됐다.
• TOC.md 는 목차가 아니라 발행 목록이다. TOC 에서 뺀 페이지는 라이브에서 삭제된다. 2026-07-26 실측: 2,243 → 249 노드, 뺀 페이지 URL 은 404, 복구 경로 없음(TOC 를 되돌리는 push 도 500 에 다시 막힌다). 리포의 pages/·mapping.json 은 전량 보존되므로 상한이 풀리면 TOC 복원으로 본문은 되돌아간다. 다만 URL 은 아니다(아래).
• 살아남은 페이지의 page_id 는 흔들리지 않는다. 같은 실측에서 생존 244개 전부 page_id 유지(변경 0). 대량 삭제와 page_id 안정성은 별개다.
• 삭제된 페이지의 page_id 는 부활하지 않는다. 2026-07-27 실측: 컷 때 지워진 두 노트가 autholog 태그로 발행면에 다시 들어오자 위키독스는 옛 381403/381716 이 아니라 새 387071/387072 를 발급했다. 그래서 mapping 의 page_id 는 그 페이지가 직전 판 발행면에 있었을 때만 살아 있다. 이 조건은 조용히 깨진다 — 죽은 id 도 숫자가 멀쩡히 있고 TOC 안이라 link_target·relink·audit 이 전부 통과한다. 라이브를 재는 status.py 의 미생성 만이 신호다. 그래서 build 가 덮어쓰기 전 TOC.md 를 읽어 발행면에 새로 들어오는 항목의 page_id 를 승계하지 않고, relink 가 가든 원본으로 내보내게 한 뒤 push→recover 로 새 id 를 받는다. 발행면 밖에 머무는 항목의 죽은 id 는 그대로 둔다 — 노출 경로가 없고, 2천여 항목을 흔들면 실제 위험 구간이 diff 에 묻힌다. 가든에서 기존 노트에 autholog 를 붙이는 것만으로 이 경로를 타므로 드문 일이 아니다.
• 회수 이력이 있는데 직전 판 발행면을 못 읽으면 build 는 멈춘다. TOC.md 가 없거나 등록 0개인데 mapping 에 page_id 가 있으면 어느 id 가 살아 있는지 판정할 수 없다. 여기서 fail-open 하면 위 안전장치가 막으려던 승계가 그대로 열리므로, 500 상한 사전검사와 같이 생성물을 건드리기 전에 실패한다(relink 의 TOC 부재 exit 1 과 같은 방향). 통과하는 것은 회수 이력 자체가 없는 순수 bootstrap 뿐이다 — 비울 id 가 없으니 위험도 없다. 정상 clone 에는 tracked TOC.md 가 있으므로 이 경로를 밟지 않는다.
• build 의 두 warning 은 층이 다르다. 발행면 page_id 미회수 N개 는 2단계 push 가 필요하다는 운영 신호로, 죽은 id 를 비운 항목과 처음 올라가는 항목을 함께 센다. 그중 M개는 발행면 신규 진입 은 그 부분집합이자 안전장치가 실제로 발동했다는 신호다. 앞의 것만 절차 트리거로 읽는다 — 뒤의 것은 0 이어도 회수는 필요할 수 있다.
• 위키독스 URL 은 발행된 페이지에만 유효하다. mapping 에 page_id 가 남아 있어도 TOC 밖이면 404 다. build --garden-links(표지·집합면)와 relink 의 TOC 게이트가 이 규칙을 강제하고, audit 이 발행면 밖 page_id 참조를 오류로 잡는다. 저자가 본문에 직접 쓴 외부 위키독스 링크는 mapping 소유가 아니므로 대상이 아니다.
• relink 는 발행면 안팎 양쪽에 게이트를 건다. 링크 대상이 TOC 안이어야 실화하고, 링크를 담은 파일도 TOC 안이어야 연다. 발행면 밖 페이지는 라이브에 없어서 그 안의 위키독스 URL 을 아무도 볼 수 없는데, 고치면 발행면이 바뀔 때마다 리포 전체가 흔들린다 (2026-07 실측: 코어 249개 발행면인데 file 게이트 없이는 826개 파일이 바뀌었고 그 중 639개가 발행면 밖이었다. 게이트 후 185개). 책 대문 README.md 만 TOC 밖 예외다. TOC.md 가 없으면 relink 는 게이트를 풀지 않고 exit 1 로 멈춘다. 발행면을 모르는 채 전량을 고치는 fail-open 이 바로 이 게이트가 막으려는 사고이기 때문이다.
• URL = page_id 기반, 매우 안정적. 파일명·제목·순서를 다 바꿔도 page_id 유지됨. 단 우리가 URL을 직접 지정할 수 없으므로 mapping.json 으로 회수·관리한다.
• 파일명 = denote-id (pages/journal/20220310T000000.md). URL 안정·회수 앵커·편집관리.
• 제목(TOC 링크텍스트) 앞에 source 날짜 8자리 접두어. journal은 garden date (주간/일간 저널이 나타내는 created date), meta/bib/notes/botlog는 garden lastmod를 쓰고 없을 때만 date로 fallback한다. build/git/file mtime/WikiDocs sync 시각은 금지한다. 제목이 선택된 source 날짜(ISO 또는 8자리)로 이미 시작하면 중복 접두어를 생략한다.
• recent-first AEO 표지. TOC.md와 각 챕터 cover는 위 source 날짜 기준 내림차순이다. WikiDocs sidebar는 제목 오름차순을 강제하므로 stable title/page_id를 깨는 순번 재부여를 하지 않는다. _chapter.md의 항목은 ## 깨끗한 원제목 → 작성·수정일·태그 → frontmatter description → 읽기 링크 순서다. TOC의 날짜접두어 subject와 표지 heading은 역할이 다르다. 같은 표지 안의 중복 제목만 — 작성일(그래도 겹치면 Denote ID)로 구분한다. 발행면 안은 WikiDocs, 밖은 garden 원본으로 보내며 링크 문구도 목적지를 밝힌다. 표지에는 [TOC]를 넣지 않는다(수백 heading 폭발 방지). audit은 exact regeneration과 별개로 item ## 수·heading 유일성·읽기 링크 수/순서를 독립 검증한다.
• 페이지 provenance 순서. 저자의 이 노트에 대하여 abstract가 있으면 abstract → 원본·최신본 → [TOC]/본문, 없으면 provenance가 첫 본문 블록이다. 블록의 exact garden source URL은 relink하지 않는다. source date/lastmod만 페이지에 표시하고 mirror sync date는 README 책 수준에만 둔다.
• mapping의 source metadata는 cache. Denote ID가 join key다. 기존 page_id, url, path, folder, subject를 호환 보존하고 source_url, source_date, source_lastmod, description, tags를 garden frontmatter에서 매 build마다 다시 파생한다. 표지에 공개되는 description/tags cache에는 본문과 같은 신원 난독화를 적용한다. description이 비면(현재 1건) 요약 문단만 생략하고 abstract를 대신 복사하지 않는다. tags/lastmod가 없으면 해당 메타 segment만 생략한다.
• 재현 입력 manifest. build는 루트 BUILD-MANIFEST.json에 garden full commit SHA, relevant source clean 여부, canonical folders/page count/book id, 선택 입력의 deterministic content SHA256을 기록한다. manifest는 commit 대상 운영 provenance이며 WikiDocs ingest 대상이 아니다. audit은 현재 garden 입력과 exact match를 검증한다. 생성 시각은 넣지 않는다.
• pages/ 서브디렉토리 지원됨. pages/<folder>/... 로 가든 폴더 구조를 미러한다.
• 폴더 = 챕터. pages/<folder>/_chapter.md에 전 항목 AEO recent-first index를 생성한다. 표지 자신도 별도 원본·최신본 provenance 블록으로 대응 가든 폴더 URL로 돌아간다. 단순 링크 목록이 아니라 제목·source 날짜·태그·description·목적지 명시 링크를 싣는다. description은 plain text를 기본으로 다루되 authored *강조*/_강조_와 중간 #태그, 기존 HTML entity는 보존한다. angle bracket의 HTML 소실과 미래의 줄 시작 Markdown block 문법만 방어하며, &를 바꿔 기존 entity를 이중 인코딩하지 않는다.
• autholog = 0순위 가상 챕터. WikiDocs에 태그 기능이 없으므로 전 canonical folder에서 frontmatter tags에 autholog가 있는 문서만 pages/autholog/_chapter.md에 모은다. 원본/본문을 복제하지 않고 폴더 표지와 같은 AEO 항목 renderer로 기존 미러 URL을 잇는다. 정렬은 폴더와 무관하게 lastmod 내림차순(date fallback, 같은 시각은 Denote ID 내림차순)이다. standalone 표지는 <!-- collection:autholog -->로 회수하며 _chapters.autholog에 page_id를 보관한다. TOC와 사용자 스크립트 탐색면에서는 authored folder보다 앞선 0 어쏠로그로 둔다. 첫 생성 때는 audit --allow-missing-page-ids → push/status → recover/relink → audit의 신규 ID 2단계가 필요하다. 그 전까지 README의 태그 링크는 가든 URL fallback이 정상이다. --core 에서도 발행한다. autholog 는 코어 정의(autholog 태그 ∪ botlog 폴더)의 절반인데 botlog 만 5 봇로그 표지로 커버되고 있었다. 이 집합면은 항목이 전부 발행면 안이라 링크 이탈이 0인 유일한 탐색면이다(2026-07 실측: 어쏠로그 170/170·봇로그 80/80 이 위키독스 내부, 노트 163/837, 메타 1/538, 저널·참고문헌 0). 발행 비용은 TOC 1칸이다.
• 사이드바 사용자 스크립트는 웹훅 밖에 있다. wikidocs-user-script.js 는 위키독스 책 설정(책 수정 > 사용자 스타일/스크립트)에 손으로 붙여넣는다. GitHub 동기화가 건드리지 않으므로 리포와 조용히 어긋날 수 있어, audit 이 CH 배열을 TOC 챕터 목록·순서와 mapping._chapters 의 page_id 에 대조한다(목록/순서 불일치·page_id 불일치·미회수인데 숫자 선언="출처 없는 ID"=오류, 회수했는데 null=경고, 파일 자체가 없으면 경고). 챕터를 더하거나 표지를 재생성하면 CH 를 고치고 위키독스에 다시 붙여넣어야 반영된다.
• 본문 맨 위 H1 없음, frontmatter 없음. 제목은 TOC 가 관리.
• 위키독스는 인제스트 때 이미지를 자기 CDN 으로 재업로드·URL 재작성한다. 로컬 ![](../../assets/x.png) → 라이브 ![](https://static.wikidocs.net/images/page/<pid>/…). 텍스트·줄수·이미지 개수/위치는 보존되고 URL 만 바뀐다. 라이브 vs 로컬 본문 대조(status.py) 는 이미지 URL 을 ![](IMG) 로 중립화해야 정확하다 — 안 하면 이미지 있는 페이지가 영영 pending 오탐으로 잡힌다.
• 회사/직장 신원 난독화 필수. scrub_identity 가 가든 change-text.sh 의 치환 규칙을 런타임에 읽어 본문뿐 아니라 AEO 표지의 title/description/tags 공개값에도 적용한다. 민감어를 이 스크립트나 문서에 하드코딩하지 않는다(그 자체가 pre-commit 훅에 걸린다). change-text.sh 가 어떤 핸들의 특정 번호 변형만 다루는 경우, build.py 가 그 베이스를 전 변형(숫자 0개 이상)으로 일반화해 훅이 막는 모든 형태를 덮는다.

변환 매핑

가든 (Quartz/Hugo)	위키독스	함수
frontmatter title/date/lastmod	journal=date, 그 외=lastmod→date의 <날짜8> <제목> + recent-first TOC	source_sort_timestamp/subject_for
frontmatter title/description/date/lastmod/tags	챕터 표지의 ## 제목 + 메타 + plain-text 요약 + 목적지 링크	public_index_metadata/index_item_blocks
본문 페이지의 frontmatter	제거	split_frontmatter
## 제목 {#anchor}	## 제목	HEAD_ANCHOR
<span class="timestamp-wrapper">…[날짜]…</span>	[날짜]	TIMESTAMP
> [!type] 제목 callout 11종+	[[TIP("라벨")]]…[[/TIP]]	convert_callouts
<div class="csl-entry">·<a href> citeproc	- 참고문헌 마크다운 목록/링크	convert_html
[텍스트]({{< relref "/x/y.md" >}})	가든 절대URL(씨뿌리기) → page_id URL(relink)	relref_repl
{{< figure src=… >}}	 → assets 복사	figure_repl
	 + assets 복사	make_images
코드펜스 ```/ ````	원형 보존(3+ backtick 개수 매칭, 줄앵커)	protect_code
회사/직장 신원	change-text.sh 규칙으로 난독화	scrub_identity

위키독스 확장문법 착지점

[[TIP]]/[[TIP("라벨")]]…[[/TIP]], [TOC], [[MARK]]/[[SMARK]]. [[SubPages]]는 WikiDocs가 지원하지만 generator는 안정적인 explicit recent-first index를 위해 의도적으로 사용하지 않는다.

배포·동기화

push 하면 웹훅이 README.md(책 대문)·TOC.md·pages/·assets/ 를 읽어 동기화 (.claude/·AGENTS.md·NEXT.md·mapping.json·BUILD-MANIFEST.json 은 무시). README.md 는 가든 content/index.md 를 변환한 책 대문이므로 index 가 바뀌면 build 가 재생성한다. 안 보이면: push 반영 확인 → GitHub Settings > Webhooks → 위키독스 책 수정 > 깃허브 연결/웹훅 → 지금 동기화. 103페이지 동기화에 ~70초. 갱신 때는 기존 page_id를 승계하므로 build → relink → audit → push로 기존 페이지를 한 번에 복구할 수 있다. 새 페이지가 있으면 동기화 뒤 recover → relink → audit → push를 한 번 더 수행한다.

대량(2천여 페이지) push 는 웹훅이 한 번에 다 안 돈다. 서버측에서 나눠 처리되거나 중간에 멈춰, 반영이 부분적으로 끝나고 지금 동기화 수동 재트리거가 몇 번 필요할 수 있다. push 후 status.py --list 로 synced/pending 을 재서 pending 이 0 이 될 때까지 확인한다(멈춰 있으면 수동 재트리거). status.py 는 커밋 범위에 안 묶이고 라이브 vs 현재 리포를 비교하므로 언제