garden-to-wikidocs

# 가든 → 위키독스 깃허브 연동 책 내보내기 (v2) 이 리포(`junghan0611/garden2wikidocs`)는 위키독스 책 **20676 "Junghanacs's Digital Garden"** 과 깃허브 연동돼 있다. `git push` → 웹훅 → 위키독스 동기화. ## 정본·발견면 계약 cross-repo 정책 SSOT는 garden의 [`docs/WIKIDOCS_MIRROR.md`](https://github.com/junghan0611/garden/blob/main/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 상한 아래) ```bash 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개` 를 찍으면 이 절차다. ```bash 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 재작성한다.** 로컬 `` → 라이브 ``. 텍스트·줄수·이미지 개수/위치는 보존되고 URL 만 바뀐다. 라이브 vs 로컬 본문 대조(status.py) 는 이미지 URL 을 `` 로 중립화해야 정확하다 — 안 하면 이미지 있는 페이지가 영영 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 현재 리포를 비교하므로 언제