@wonseok-han/confluence-sync 1.2.1 → 1.4.0

package/README.md

@@ -20,7 +20,7 @@ confluence-sync --version
 confluence-sync --help
 ```
 
-공개 npm 패키지라 **토큰이나 `.npmrc` 설정이 필요 없습니다.** (Node 20+)
+공개 npm 패키지라 **토큰이나 `.npmrc` 설정이 필요 없습니다.** (Node 22.13+)
 
 > 짧은 이름 **`csync`** 도 같이 설치됩니다 — 아래 예시의 `confluence-sync` 는 전부 `csync` 로 바꿔 쓸 수 있습니다.
 
@@ -144,6 +144,7 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 | 쓰는 것 | Confluence 에서 |
 | --- | --- |
 | `[§1 개요](#1-개요)` | 같은 페이지의 그 헤딩으로 이동 |
+| `[[#1. 개요]]` · `[[#1. 개요\|§1]]` | 위와 동일 (Obsidian 표기) |
 | `[§6 ZKP](./04-구현체.md#6-zkp)` | 그 페이지의 그 헤딩으로 이동 |
 | `[[04-구현체#6. ZKP]]` | 위와 동일 (Obsidian 표기) |
 
@@ -165,6 +166,7 @@ pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니
 
 - 문서의 `제목 + 본문 + 참조 이미지 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
 - 매핑은 **`<base>/.confluence-sync.json`** 에 저장됩니다. **문서셋과 함께 커밋하세요** — 지우면 다음 실행에서 페이지가 중복 생성됩니다. (`--mapping <path>` 로 위치 변경 가능)
+- **pull 도 같은 매핑에 기록합니다** — 그래서 pull 직후 push 하면 `= 변경없음` 입니다. [Pull → 매핑 기록](#매핑-기록) 참고.
 - Confluence 에서 페이지가 삭제됐다면 자동으로 **재생성**하고, 그 페이지를 가리키던 문서들도 **링크를 다시 연결**합니다. 내용이 그대로라 스킵되는 경우까지 잡으려면 `--verify` 를 씁니다.
 
 ### 동기화 제외 (로컬 전용 문서 유지)
@@ -211,6 +213,25 @@ confluence-sync pull --space --obsidian --out ~/MyVault   # 내부 링크를 [[w
 
 > **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다.
 
+### 매핑 기록
+
+pull 은 받아온 문서를 **매핑 파일에 함께 기록합니다** — 페이지 id 와, push 가 계산하는 것과 **같은 방식의 변경 해시**를 남깁니다. 그래서 **pull 직후 push 하면 `= 변경없음`** 입니다. 이게 없으면 매핑에 해시가 없어 방금 받아온 내용을 그대로 되올려 보내게 됩니다.
+
+```bash
+$ confluence-sync pull --space --out ./docs
+  …
+완료  페이지 42개, 폴더 3개 생성  내부링크 88개 연결  매핑 45건
+  매핑: /repo/docs/.confluence-sync.json  (base: /repo/docs)
+
+$ confluence-sync --base ./docs --dry-run
+  [동일] …          # 되올려 보낼 것이 없다
+```
+
+- **base 는 `--out` 에서 위로 올라가며 `.confluence-sync.json` 을 찾아 정합니다.** 매핑 키는 base 기준 상대경로여야 이어지는 push 가 같은 문서를 알아보기 때문입니다. 하위 폴더로 받아도(`--out <base>/일부`) 루트의 매핑에 제대로 들어갑니다.
+- 못 찾으면 `--out` 자체가 base 가 됩니다(그 디렉토리가 곧 동기화 루트가 됩니다).
+- **`--base <dir>`** · **`--mapping <path>`** 로 직접 지정할 수 있고, **`--no-mapping`** 이면 아무것도 쓰지 않습니다.
+- 같은 페이지가 다른 키에 남아 있으면(문서를 옮겼으면) 옛 키를 걷어내 중복 항목을 만들지 않습니다.
+
 ---
 
 ## Obsidian
@@ -275,6 +296,16 @@ confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
 - 파일명이 트리 안에서 겹치면(`README.md` 여러 개 등) `[[wikilink]]` 로 바꾸지 않고 상대 링크를 유지합니다 — 이름만으로는 어느 노트인지 확정할 수 없기 때문입니다.
 - 코드블록·인라인 코드 안의 링크는 손대지 않습니다.
 - **섹션 링크는 표기가 다릅니다** — 표준 마크다운은 슬러그(`문서.md#6-zkp`), Obsidian 은 헤딩 텍스트(`[[문서#6. ZKP]]`)를 씁니다. 대상 문서의 헤딩을 찾아 옮기고, 못 찾으면 섹션 없이 문서 링크로 둡니다. Obsidian 블록 참조(`#^id`)는 마크다운에 대응물이 없어 같은 방식으로 처리합니다.
+- **같은 문서 섹션**도 마찬가지입니다 — `[§4](#4-버전)` ↔ `[[#4. 버전|§4]]`. 표 안에서 `\|` 로 이스케이프된 별칭도 인식합니다.
+
+### 각주와 첨부
+
+`--to markdown`은 각주를 위첨자 링크와 작은 제목으로 변환하고, 각주에 연결된 PDF의
+`#page=N` 페이지를 이미지로 표시합니다. 첨부파일은 `attachments/`에 모아 연결합니다.
+PDF 이미지 추출은 패키지에 포함된 PDF.js로 처리하므로 별도 도구 설치가 필요 없습니다.
+
+`--to obsidian`은 변환 정보와 원본 PDF가 남아 있는 로컬 변환본에서 각주와 PDF 참조를 복원합니다.
+Confluence에서 다시 내려받은 문서의 복원은 보장하지 않습니다.
 
 ### 보정 (`--fix`)
 
@@ -296,6 +327,8 @@ confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
 | vault 에서 쓴 것 | Confluence 에 올라가는 것 |
 | --- | --- |
 | `[[설계]]` · `[[구조/설계\|설계 문서]]` | 페이지 링크 (짧은 이름·경로 모두 인식) |
+| `[[설계#3. 구성]]` | 그 페이지의 그 섹션 |
+| `[[#3. 구성]]` · `[[#3. 구성\|§3]]` | **같은 페이지**의 그 섹션 |
 | `![[diagram.png]]` | 첨부 이미지 |
 | frontmatter `title:` | 페이지 제목 |
 | frontmatter `pageId:` | **그 페이지를 갱신** (새로 만들지 않음) |
@@ -310,6 +343,8 @@ confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
 
 ## 개발
 
+`npm test`로 전체 테스트, `npm run test:coverage`로 커버리지를 확인합니다. 테스트는 실제 Confluence에 접속하지 않습니다.
+
 ```bash
 git clone https://github.com/wonseok-han/confluence-sync.git
 cd confluence-sync

package/dist/anchors.js

@@ -10,11 +10,33 @@
  * 이름은 마크다운 슬러그를 그대로 쓰므로 왕복도 정확해진다 — 양쪽 다 우리가 정한 값이다.
  */
 const FENCE = /^\s*(?:```|~~~)/;
+/**
+ * `[[대상]]` · `[[대상|별칭]]` · `[[대상#헤딩]]` · `[[#헤딩]]` · `![[임베드]]`
+ *
+ * 대상이 **비어 있을 수 있다** — `[[#헤딩]]` 은 "이 문서의 이 섹션"이라는 Obsidian 표기다.
+ * 표 안에서는 별칭 앞 파이프가 `\|` 로 이스케이프되므로 그 백슬래시도 함께 받아 준다.
+ */
+export const WIKILINK_RE = /(!?)\[\[([^[\]|#]*)(#[^[\]|]+)?(?:\\?\|([^[\]]*))?\]\]/g;
+/**
+ * WIKILINK_RE 의 캡처 그룹을 해석한다. 대상도 섹션도 없으면(`[[]]`) 링크가 아니므로 null.
+ * 표의 `\|` 때문에 앞 그룹 끝에 딸려온 백슬래시는 여기서 떼어낸다.
+ */
+export function parseWikilink(bang, target, hash, alias) {
+    const unesc = (s) => s.replace(/\\$/, '').trim();
+    const t = unesc(target ?? '');
+    const f = hash ? unesc(hash.slice(1)) : null;
+    if (!t && !f)
+        return null;
+    return { embed: bang === '!', target: t, fragment: f || null, alias: alias?.trim() || null };
+}
 /** 인라인 마크다운 표기를 벗긴다 — 슬러그는 렌더된 텍스트 기준이다. */
 function plainText(s) {
     return s
         .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // [label](url) → label
-        .replace(/\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|([^\]]+))?\]\]/g, (_m, t, a) => a ?? t)
+        .replace(WIKILINK_RE, (whole, ...g) => {
+        const w = parseWikilink(g[0], g[1], g[2], g[3]);
+        return w ? (w.alias ?? (w.target || w.fragment) ?? whole) : whole;
+    })
         .replace(/`+/g, '')
         .replace(/\*\*|~~|\*/g, '') // _ 는 남긴다: 슬러그가 밑줄을 보존하므로(foo_bar → foo_bar)
         .trim();
@@ -114,7 +136,6 @@ export function wikilinkAnchorToSlug(anchor) {
     return slugifyHeading(last) || null;
 }
 const MD_LINK = /\[([^\]]*)\]\((<[^>]+>|[^()\s]+)\)/g;
-const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
 /**
  * 본문에서 **앵커가 붙은 링크만** 훑는다 — 어느 문서의 어느 헤딩에 앵커를 심어야 하는지 알아내기 위해서다.
  * 전체 렌더보다 훨씬 싸고, 코드블록·인라인 코드·이미지는 제외한다.
@@ -142,10 +163,11 @@ export function collectLinkAnchors(md) {
                 continue;
             out.push({ dest: d.slice(0, i), fragment: d.slice(i + 1), wiki: false });
         }
-        for (const m of prose.matchAll(WIKILINK)) {
-            if (m[1] === '!' || !m[3])
+        for (const m of prose.matchAll(WIKILINK_RE)) {
+            const w = parseWikilink(m[1], m[2], m[3], m[4]);
+            if (!w || w.embed || !w.fragment)
                 continue; // 임베드·앵커 없는 wikilink
-            out.push({ dest: m[2].trim(), fragment: m[3].slice(1), wiki: true });
+            out.push({ dest: w.target, fragment: w.fragment, wiki: true }); // dest 가 비면 같은 문서
         }
     }
     return out;

package/dist/attachments.js

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { resolve, relative, dirname, basename, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mapMarkdownText } from './pdf-pages.js';
+/** 출력 트리의 경로와 실제 입력 파일을 연결한다. dry-run에서도 파일 복사 없이 사용한다. */
+export function attachmentMapper(file, base) {
+    const copies = new Map(); // base 상대 출력 경로 → 입력 절대경로
+    function localPath(raw) {
+        if (!raw || raw.startsWith('#') || raw.startsWith('//'))
+            return null;
+        if (/^file:/i.test(raw))
+            return fileURLToPath(raw);
+        if (!isAbsolute(raw) && /^[a-z][a-z\d+.-]*:/i.test(raw))
+            return null;
+        try {
+            return resolve(dirname(file), decodeURIComponent(raw));
+        }
+        catch {
+            return null;
+        }
+    }
+    function relocate(raw, wiki = false) {
+        const hash = raw.indexOf('#');
+        const path = hash < 0 ? raw : raw.slice(0, hash), fragment = hash < 0 ? '' : raw.slice(hash);
+        const abs = wiki && !path.startsWith('/') && !path.startsWith('.') && !/^file:/i.test(path)
+            ? resolve(base, path) : localPath(path);
+        if (!abs || /\.md$/i.test(abs))
+            return null;
+        // 일반 외부 URL 및 없는 링크는 그대로 남긴다.
+        if (!existsSync(abs) || !statSync(abs).isFile())
+            return null;
+        let rel = relative(base, abs).split('\\').join('/');
+        if (!rel.startsWith('attachments/')) {
+            const hash = createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 24);
+            rel = `attachments/files/${hash}/${basename(abs)}`;
+        }
+        copies.set(rel, abs);
+        const target = wiki ? rel : relative(dirname(file), resolve(base, rel)).split('\\').join('/');
+        return target + fragment;
+    }
+    function rewrite(text) {
+        return mapMarkdownText(text, part => {
+            const md = part.replace(/(?<!!)(!?)\[([^\]\n]*)\]\((<[^>\n]+>|[^()\s]+)\)/g, (all, bang, label, raw, offset) => {
+                if ((part.slice(0, offset).match(/\\+$/)?.[0].length ?? 0) % 2)
+                    return all;
+                const dest = relocate(raw.replace(/^<(.*)>$/, '$1'));
+                return dest === null ? all : `${bang}[${label}](<${dest.replace(/</g, '%3C').replace(/>/g, '%3E')}>)`;
+            });
+            return md.replace(/(!?)\[\[([^\]|\n]+)(?:\|([^\]\n]*))?\]\]/g, (all, bang, target, label, offset) => {
+                if ((md.slice(0, offset).match(/\\+$/)?.[0].length ?? 0) % 2)
+                    return all;
+                const dest = relocate(target, true);
+                return dest === null ? all : `${bang}[[${dest}${label === undefined ? '' : '|' + label}]]`;
+            });
+        });
+    }
+    return { copies, rewrite, source: (abs) => copies.get(relative(base, abs).split('\\').join('/')) ?? abs };
+}

package/dist/convert.js

@@ -9,11 +9,14 @@
  * 스페이스를 통째로 다시 받지 않고도 최신 변환 품질을 얻기 위한 것이다.
  * 링크는 대상이 트리 안에 실제로 있을 때만 바꾼다(외부 URL·이미지·깨진 링크는 손대지 않는다).
  */
-import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
-import { resolve, relative, dirname, basename, join } from 'node:path';
+import { attachmentMapper } from './attachments.js';
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, copyFileSync, realpathSync } from 'node:fs';
+import { resolve, relative, dirname, basename, join, isAbsolute } from 'node:path';
 import { collectMarkdown, collectAssets, buildVault, vaultResolver } from './docs.js';
 import { linksToWikilinks, resolveWikilinks, splitFrontmatter } from './obsidian.js';
 import { buildAnchorIndex } from './anchors.js';
+import { footnotesToLinks, linksToFootnotes } from './footnotes.js';
+import { extractPdfPages, restorePdfReferences, mapMarkdownText } from './pdf-pages.js';
 import { repairMarkdown, totalFixes } from './repair.js';
 import { bold, cyan, dim, gray, green, red, yellow } from './colors.js';
 function optVal(argv, name) {
@@ -27,17 +30,27 @@ catch {
     return s;
 } };
 const posix = (s) => s.split('\\').join('/');
-// ![alt](경로) — 본문이 참조하는 로컬 이미지(--out 으로 복사할 때 같이 옮긴다)
-const IMAGE = /!\[[^\]]*\]\((<[^>]+>|[^()\s]+)\)/g;
+const isWithin = (base, path) => {
+    const rel = relative(base, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\') && !isAbsolute(rel));
+};
+function canonical(path) {
+    if (existsSync(path))
+        return realpathSync(path);
+    const parent = dirname(path);
+    return parent === path ? path : join(canonical(parent), basename(path));
+}
+// 이미지·일반 링크의 로컬 첨부(--out 으로 복사할 때 PDF도 같이 옮긴다).
+const ASSET_LINK = /!?\[[^\]]*\]\((<[^>]+>|[^()\s]+)\)/g;
 /** md 본문이 참조하는 로컬 첨부의 절대경로들(외부 URL 제외, 실제 존재하는 것만). */
 function referencedAssets(text, fileAbs) {
     const out = [];
-    for (const m of text.matchAll(IMAGE)) {
+    for (const m of text.matchAll(ASSET_LINK)) {
         const dest = decode(m[1].replace(/^<(.*)>$/, '$1')).split('#')[0];
         if (/^(https?:|data:)/i.test(dest))
             continue;
         const abs = resolve(dirname(fileAbs), dest);
-        if (existsSync(abs))
+        if (existsSync(abs) && statSync(abs).isFile() && !/\.md$/i.test(abs))
             out.push(abs);
     }
     return out;
@@ -62,11 +75,27 @@ function commonAncestor(paths) {
  * wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 트리 안에서 유일할 때만 바꾼다
  * (겹치면 엉뚱한 노트로 이어질 수 있어 상대 링크를 그대로 둔다).
  */
-function toObsidian(text, fileAbs, baseDir, nameCount, headingOf) {
+function toObsidian(text, fileAbs, baseDir, nameCount, headingOf, selfHeadingOf, source = p => p) {
     return linksToWikilinks(text, (dest, label) => {
-        if (/^(https?:|mailto:|#)/i.test(dest))
-            return null; // 외부 링크·같은 문서 앵커
+        if (/^(https?:|mailto:)/i.test(dest))
+            return null; // 외부 링크
+        // 같은 문서 섹션: [§4](#슬러그) → [[#헤딩 텍스트|§4]]
+        // Obsidian 은 슬러그가 아니라 헤딩 텍스트로 섹션을 가리키므로, 헤딩을 못 찾으면 손대지 않는다.
+        if (dest.startsWith('#')) {
+            const heading = selfHeadingOf(decode(dest.slice(1)));
+            if (!heading)
+                return null;
+            const l = label.trim();
+            return l && l !== heading ? `[[#${heading}|${l}]]` : `[[#${heading}]]`;
+        }
         const [pathPart, ...hash] = decode(dest).split('#');
+        if (/\.pdf$/i.test(pathPart)) {
+            const target = resolve(dirname(fileAbs), pathPart);
+            const rel = relative(baseDir, target).split('\\').join('/');
+            if (!existsSync(source(target)) || rel.startsWith('../'))
+                return null;
+            return `[[${rel}${hash.length ? '#' + hash.join('#') : ''}|${label}]]`;
+        }
         if (!/\.md$/i.test(pathPart))
             return null;
         const targetAbs = resolve(dirname(fileAbs), pathPart);
@@ -158,7 +187,7 @@ export async function runConvert(argv) {
     const selected = targets.length
         ? allMd.filter((f) => targets.some((t) => {
             const abs = resolve(t);
-            return f === abs || f.startsWith(abs + '/');
+            return isWithin(abs, f);
         }))
         : allMd;
     // base 밖의 .md 를 직접 지목한 경우(예: 이웃 폴더 파일) 는 위 필터에 안 걸린다
@@ -180,7 +209,7 @@ export async function runConvert(argv) {
     const scope = mdAbs.length === allMd.length
         ? `${mdAbs.length}건`
         : `선택 ${mdAbs.length}/${allMd.length}건`;
-    if (outDir && (outDir === baseDir || outDir.startsWith(baseDir + '/'))) {
+    if (outDir && isWithin(canonical(baseDir), canonical(outDir))) {
         console.error(red(`✗ --out 이 base 안에 있습니다: ${outDir}`) + dim('\n  원본 트리를 덮어쓰지 않도록 base 밖의 경로를 쓰세요.'));
         process.exit(1);
     }
@@ -195,7 +224,9 @@ export async function runConvert(argv) {
         const rel = posix(relative(baseDir, abs));
         const before = readFileSync(abs, 'utf8');
         let text = before;
+        const sourceAssets = new Set(to === 'obsidian' ? [] : referencedAssets(before, abs));
         const notes = [];
+        const attachments = attachmentMapper(abs, baseDir);
         // 보정을 먼저 한다 — 이스케이프가 풀려야(\[…\] → […]) 링크 인식이 정확해진다
         if (fix) {
             const r = repairMarkdown(text);
@@ -207,20 +238,61 @@ export async function runConvert(argv) {
                 notes.push(dim(`보정 ${n}`));
             }
         }
-        if (to === 'obsidian')
-            text = toObsidian(text, abs, baseDir, nameCount, headingOf);
-        else if (to === 'markdown')
-            text = resolveWikilinks(text, vaultResolver(rel, vault));
+        if (to === 'obsidian') {
+            const restored = restorePdfReferences(text, abs, baseDir);
+            restored.assets.forEach(a => sourceAssets.add(a));
+            referencedAssets(restored.text, abs).forEach(a => sourceAssets.add(a));
+            text = attachments.rewrite(linksToFootnotes(restored.text));
+            // 같은 문서 앵커는 보정(--fix)까지 끝난 **지금 본문**의 헤딩으로 풀어야 맞는다
+            const selfIdx = buildAnchorIndex(splitFrontmatter(text).body);
+            text = toObsidian(text, abs, baseDir, nameCount, headingOf, (s) => selfIdx.get(s.toLowerCase()), attachments.source);
+        }
+        else if (to === 'markdown') {
+            const lookup = vaultResolver(rel, vault);
+            // 명시된 첨부 경로를 먼저 출력 트리로 옮긴 뒤 wiki 이름을 해석한다.
+            text = attachments.rewrite(text);
+            text = resolveWikilinks(text, (target, embed) => {
+                const imported = resolve(baseDir, target);
+                if (attachments.copies.has(posix(relative(baseDir, imported)))) {
+                    return posix(relative(dirname(abs), imported));
+                }
+                return lookup(target, embed);
+            });
+            text = footnotesToLinks(attachments.rewrite(text));
+            mapMarkdownText(text, part => {
+                if (/\[\[[^\]\n]*\.pdf#page=[^\]\n]*\]\]/i.test(part)) {
+                    throw new Error(`PDF 위키링크를 해석하지 못했습니다 (${rel}). --base에 PDF가 포함되는지 확인하세요.`);
+                }
+                return part;
+            });
+            const pdf = await extractPdfPages(text, abs, baseDir, outDir ?? baseDir, dryRun, attachments.source);
+            pdf.assets.forEach(a => sourceAssets.add(a));
+            text = pdf.text;
+            if (pdf.pages)
+                notes.push(dim(`PDF ${pdf.pages}쪽 이미지`));
+        }
         // 제자리 변환이면 바뀐 것만 쓰지만, --out 이면 대상 전부를 내보낸다(온전한 트리가 나와야 하므로)
         if (!outDir && text === before)
             continue;
+        if (!dryRun) {
+            for (const [assetRel, source] of attachments.copies) {
+                const destination = join(outDir ?? baseDir, assetRel);
+                if (destination !== source) {
+                    mkdirSync(dirname(destination), { recursive: true });
+                    copyFileSync(source, destination);
+                }
+                copiedAssets.add(assetRel);
+            }
+        }
         if (outDir) {
             const target = join(outDir, rel);
             if (!dryRun) {
                 mkdirSync(dirname(target), { recursive: true });
                 writeFileSync(target, text);
-                // 이미지가 따라가지 않으면 링크가 깨진다 — 참조된 첨부를 같은 상대 위치로 복사
-                for (const asset of referencedAssets(text, abs)) {
+                // 참조된 첨부를 같은 상대 위치로 복사한다.
+                for (const asset of new Set([...sourceAssets, ...referencedAssets(text, abs)])) {
+                    if ([...attachments.copies.values()].includes(asset))
+                        continue;
                     const arel = posix(relative(baseDir, asset));
                     if (arel.startsWith('..') || copiedAssets.has(arel))
                         continue; // base 밖 첨부는 두고 온다

package/dist/docs.js

@@ -97,7 +97,8 @@ export function resolveAnchorTargets(docs, vault) {
             let target;
             let slug;
             if (la.wiki) {
-                target = vault.notes[la.dest.toLowerCase().replace(/\.md$/i, '')] ?? null;
+                // dest 가 비면 `[[#헤딩]]` — 같은 문서의 섹션이다
+                target = la.dest === '' ? rel : (vault.notes[la.dest.toLowerCase().replace(/\.md$/i, '')] ?? null);
                 slug = wikilinkAnchorToSlug(la.fragment);
             }
             else {
@@ -218,7 +219,7 @@ export function resolveSelection(rels, positionals, baseDir) {
     const set = new Set();
     for (const p of positionals) {
         const abs = resolve(baseDir, p);
-        const relToBase = relative(baseDir, abs);
+        const relToBase = relative(baseDir, abs).split('\\').join('/');
         if (relToBase.startsWith('..')) {
             console.error(`  ⚠ base 밖 경로 무시: ${p}`);
             continue;

package/dist/footnotes.js

@@ -0,0 +1,110 @@
+import MarkdownIt from 'markdown-it';
+import footnote from 'markdown-it-footnote';
+import { collectHeadings } from './anchors.js';
+import { mapMarkdownText, replaceGeneratedBlocks } from './pdf-pages.js';
+/** 각주 확장을 일반 제목 앵커 + 위첨자 Markdown 링크로 내보낸다. */
+export function footnotesToLinks(source) {
+    if (!source.includes('[^'))
+        return source;
+    const md = new MarkdownIt({ html: true }).use(footnote);
+    const definitions = [];
+    const lines = source.split('\n');
+    const offsets = [0];
+    for (const line of lines)
+        offsets.push(offsets[offsets.length - 1] + line.length + 1);
+    const defRule = md.block.ruler.getRules('').find((r) => r.name === 'footnote_def');
+    md.block.ruler.at('footnote_def', (state, start, end, silent) => {
+        const ok = defRule(state, start, end, silent);
+        if (ok && !silent) {
+            const first = lines[start].match(/^ {0,3}\[\^([^\]]+)\]:\s*(.*)$/);
+            if (first)
+                definitions.push({
+                    start: offsets[start], end: Math.min(offsets[state.line], source.length), label: first[1],
+                    body: [first[2], ...lines.slice(start + 1, state.line).map((l) => l.replace(/^(?: {4}|\t)/, ''))].join('\n').trimEnd(),
+                });
+        }
+        return ok;
+    }, { alt: ['paragraph', 'reference'] });
+    const env = {};
+    const tokens = md.parse(source, env);
+    if (!definitions.length)
+        return source;
+    const used = new Set(collectHeadings(source).map((h) => h.slug));
+    const labels = new Set(definitions.map((d) => d.label));
+    const notes = new Map();
+    const edits = [];
+    const refRule = md.inline.ruler.getRules('').find((r) => r.name === 'footnote_ref');
+    let localEdits = [];
+    md.inline.ruler.at('footnote_ref', (state, silent) => {
+        const start = state.pos;
+        const ok = refRule(state, silent);
+        if (ok && !silent) {
+            const label = state.src.slice(start + 2, state.pos - 1);
+            if (!labels.has(label))
+                return ok; // 지원 범위 밖의 중첩 정의는 원문으로 남긴다.
+            let note = notes.get(label);
+            if (!note) {
+                const number = notes.size + 1;
+                let heading = `각주 ${number}`, anchor = `각주-${number}`, suffix = 0;
+                while (used.has(anchor)) {
+                    heading = `각주 ${number}-${++suffix}`;
+                    anchor = `각주-${number}-${suffix}`;
+                }
+                used.add(anchor);
+                note = { number, heading, anchor };
+                notes.set(label, note);
+            }
+            localEdits.push({ start, end: state.pos, text: `<sup>[${note.number}](#${note.anchor})</sup>` });
+        }
+        return ok;
+    });
+    // 인라인 각주(^[...])는 이 변환의 대상이 아니다.
+    md.inline.ruler.disable('footnote_inline');
+    const replaceRefs = (text) => {
+        localEdits = [];
+        md.inline.parse(text, md, env, []);
+        for (const e of localEdits.sort((a, b) => b.start - a.start))
+            text = text.slice(0, e.start) + e.text + text.slice(e.end);
+        return text;
+    };
+    // 코드블록과 정의를 제외한 원문 구간을 그대로 보존한다.
+    const excluded = [
+        ...definitions.map((d) => ({ start: d.start, end: d.end, definition: true })),
+        ...tokens.filter((t) => (t.type === 'fence' || t.type === 'code_block' || t.type === 'html_block') && t.map)
+            .map((t) => ({ start: offsets[t.map[0]], end: Math.min(offsets[t.map[1]], source.length), definition: false })),
+    ].sort((a, b) => a.start - b.start);
+    let cursor = 0;
+    for (const span of excluded) {
+        if (span.start < cursor)
+            continue;
+        edits.push({ start: cursor, end: span.start, text: replaceRefs(source.slice(cursor, span.start)) });
+        if (span.definition)
+            edits.push({ start: span.start, end: span.end, text: '' });
+        cursor = span.end;
+    }
+    edits.push({ start: cursor, end: source.length, text: replaceRefs(source.slice(cursor)) });
+    // 참조하지 않은 정의도 버리지 않는다.
+    for (const d of definitions)
+        if (!notes.has(d.label))
+            replaceRefs(`[^${d.label}]`);
+    let result = source;
+    for (const e of edits.sort((a, b) => b.start - a.start))
+        result = result.slice(0, e.start) + e.text + result.slice(e.end);
+    const bodies = new Map(definitions.map((d) => [d.label, d.body]));
+    return result.trimEnd() + '\n\n' + [...notes].map(([label, note]) => `<!-- csync-footnote:v1 ${Buffer.from(JSON.stringify({ label, anchor: note.anchor })).toString('base64')} -->\n###### ${note.heading}\n\n${replaceRefs(bodies.get(label) ?? '')}\n<!-- /csync-footnote -->`).join('\n\n') + '\n';
+}
+/** 생성 표식이 있는 각주만 복원한다. 설명의 사용자 수정은 유지한다. */
+export function linksToFootnotes(source) {
+    const refs = new Map();
+    const definitions = [];
+    const text = replaceGeneratedBlocks(source, /<!-- csync-footnote:v1 ([A-Za-z0-9+/=]+) -->\n#{1,6} [^\n]+\n\n([\s\S]*?)\n<!-- \/csync-footnote -->/g, (_all, encoded, body) => {
+        const { label, anchor } = JSON.parse(Buffer.from(encoded, 'base64').toString());
+        refs.set(anchor, label);
+        definitions.push(`[^${label}]: ${body.trimEnd().split('\n').join('\n    ')}`);
+        return '';
+    });
+    if (!refs.size)
+        return source;
+    const replace = (s) => mapMarkdownText(s, p => p.replace(/<sup>\[\d+\]\(#([^\s)]+)\)<\/sup>/g, (all, anchor) => refs.has(decodeURIComponent(anchor)) ? `[^${refs.get(decodeURIComponent(anchor))}]` : all));
+    return replace(text).trimEnd() + '\n\n' + definitions.map(replace).join('\n\n') + '\n';
+}

package/dist/help.js

@@ -50,14 +50,22 @@ ${h('pull(역방향) 옵션:')}
   ${o('--out <dir>')}         .md 를 생성할 디렉토리(기본: 현재 폴더)
   ${o('--children')}          하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
   ${o('--space')}             대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
-  ${o('--obsidian')}       내부 링크를 [[wikilink]] 로 출력(기본: 어디서나 열리는 상대 .md 링크)
+  ${o('--obsidian')}          내부 링크를 [[wikilink]] 로 출력(기본: 어디서나 열리는 상대 .md 링크)
+  ${o('--base <dir>')}        매핑 키의 기준(기본: --out 에서 위로 올라가며 .confluence-sync.json 을 찾음)
+  ${o('--mapping <path>')}    매핑 파일 위치 (기본: <base>/.confluence-sync.json)
+  ${o('--no-mapping')}        매핑을 기록하지 않음
   (이미지는 항상 attachments/<문서명>/ 하위에 저장됨)
+  받아온 문서는 pageId 와 ${dim('변경 해시')}가 매핑에 기록되어, ${bold('pull 직후 push 하면 "변경없음"')} 입니다
+  ${dim('(기록하지 않으면 방금 받아온 내용을 그대로 되올려 보내게 됩니다).')}
   예)  ${o('confluence-sync pull https://.../pages/12345/Title --out ./docs --children')}
        ${o('confluence-sync pull --space --out ./docs')}
 
 ${h('convert(이미 받아둔 .md 손보기) 옵션:')} ${dim('Confluence 호출·인증 없음')}
   ${o('--to obsidian')}    상대 .md 링크 → [[wikilink]]
   ${o('--to markdown')}    [[wikilink]] · ![[embed]] → 상대 .md 링크 (되돌리기)
+                   각주 → 위첨자 링크·제목 앵커, PDF #page=N → 해당 쪽 이미지
+                   --to obsidian은 변환 표식으로 각주·PDF 참조를 복원
+                   절대경로·file://·../ 로컬 첨부는 출력 트리에 복사하고 링크 변경
   ${o('--fix')}            옛 pull 결과 보정 — 코드블록 언어(java→plaintext)·CSS 잔해·
                    불필요한 \\ 이스케이프·리스트 사이 빈 줄
   ${o('--base <dir>')}     링크를 해석할 문서 트리 루트(기본: 준 경로들의 공통 상위 폴더)
@@ -72,7 +80,7 @@ ${h('convert(이미 받아둔 .md 손보기) 옵션:')} ${dim('Confluence 호출
 
 ${h('섹션 링크(앵커):')}
   ${o('[§1 개요](#1-개요)')} 처럼 헤딩을 가리키는 링크가 Confluence 에서도 동작합니다.
-  같은 문서(${o('#슬러그')})·다른 문서(${o('문서.md#슬러그')})·Obsidian(${o('[[문서#헤딩]]')}) 모두 지원합니다.
+  같은 문서(${o('#슬러그')} · ${o('[[#헤딩]]')})·다른 문서(${o('문서.md#슬러그')} · ${o('[[문서#헤딩]]')}) 모두 지원합니다.
   Confluence 의 자동 헤딩 id 는 배포판마다 달라서, 가리켜지는 헤딩 앞에 ${dim('Anchor 매크로')}로
   이름을 직접 심고 그 이름을 가리킵니다. pull 은 반대로 슬러그를 되돌립니다.
   대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 ${dim('⚠ 대응 헤딩 없는 앵커')} 로 알려 줍니다

package/dist/mapping.js

@@ -3,6 +3,8 @@
  * 기본 위치는 <base>/.confluence-sync.json 이며 문서셋과 함께 버전관리된다.
  */
 import { readFileSync, writeFileSync } from 'node:fs';
+/** base 루트에 놓이는 매핑 파일 이름. 이 파일이 있는 곳이 곧 동기화 루트다. */
+export const MAPPING_FILE = '.confluence-sync.json';
 export function loadMapping(path) {
     try {
         return JSON.parse(readFileSync(path, 'utf8'));

package/dist/markdown.js

@@ -57,7 +57,7 @@ function resolveInternalLink(href) {
     const [pathPart, ...rest] = href.split('#');
     if (!pathPart || !/\.md$/i.test(pathPart))
         return null;
-    const rel = relative(baseDir, resolve(baseDir, ctx.fileDir, decodePath(pathPart)));
+    const rel = relative(baseDir, resolve(baseDir, ctx.fileDir, decodePath(pathPart))).split('\\').join('/');
     const title = ctx.titleIndex[rel];
     if (!title)
         return null;
@@ -77,6 +77,13 @@ md.renderer.rules.heading_open = (tokens, idx, opts, _env, self) => {
 md.renderer.rules.fence = (tokens, idx) => {
     const t = tokens[idx];
     const lang = (t.info || '').trim().split(/\s+/)[0];
+    // 별도 호스팅한 PDF.js 등 웹 뷰어를 Confluence iFrame 매크로로 표시.
+    if (lang === 'confluence-iframe') {
+        const url = t.content.trim();
+        if (!/^https?:\/\/[^\s<>]+$/i.test(url))
+            throw new Error('confluence-iframe에는 HTTP(S) URL 한 줄이 필요합니다.');
+        return `<ac:structured-macro ac:name="iframe"><ac:parameter ac:name="url">${escapeXml(url)}</ac:parameter><ac:parameter ac:name="width">100%</ac:parameter><ac:parameter ac:name="height">900</ac:parameter></ac:structured-macro>\n`;
+    }
     const safe = t.content.split(']]>').join(']]]]><![CDATA[>');
     const langParam = lang ? `<ac:parameter ac:name="language">${lang}</ac:parameter>` : '';
     return `<ac:structured-macro ac:name="code">${langParam}<ac:plain-text-body><![CDATA[${safe}]]></ac:plain-text-body></ac:structured-macro>\n`;

package/dist/obsidian.js

@@ -9,10 +9,8 @@
  * frontmatter 는 평면 `key: value` 만 다룬다. 중첩·리스트가 필요할 만큼 복잡한 메타데이터는
  * 이 도구의 관심사가 아니며, 알 수 없는 키는 건드리지 않고 보존한다.
  */
-import { wikilinkAnchorToSlug } from './anchors.js';
+import { wikilinkAnchorToSlug, WIKILINK_RE, parseWikilink } from './anchors.js';
 const FENCE = /^\s*(?:```|~~~)/;
-// [[대상]] · [[대상|별칭]] · [[대상#헤딩]] · ![[임베드]]
-const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
 /**
  * 문서 맨 앞의 YAML frontmatter 를 분리한다. 없으면 data 는 빈 객체.
  * `key: value` 한 줄짜리만 인식하고, 값의 감싼 따옴표는 벗긴다.
@@ -69,17 +67,27 @@ function mapProse(md, fn) {
  * 해석에 실패한 링크는 원문 그대로 남겨 (조용히 사라지지 않고) 눈에 띄게 한다.
  */
 export function resolveWikilinks(md, resolve) {
-    return mapProse(md, (s) => s.replace(WIKILINK, (whole, bang, target, hash, alias) => {
-        const embed = bang === '!';
-        const found = resolve(target.trim(), embed);
+    return mapProse(md, (s) => s.replace(WIKILINK_RE, (whole, bang, target, hash, alias) => {
+        const w = parseWikilink(bang, target, hash, alias);
+        if (!w)
+            return whole;
+        // Obsidian 은 섹션을 헤딩 텍스트로 가리키지만(`#1. 신뢰 — Trust Registry`)
+        // 표준 마크다운은 슬러그를 쓴다. 블록 참조(`#^id`)는 대응물이 없어 섹션을 떼어 낸다.
+        const slug = w.fragment
+            ? (/\.pdf$/i.test(w.target) ? w.fragment : wikilinkAnchorToSlug(w.fragment))
+            : null;
+        // [[#헤딩]] — 대상이 없으면 "이 문서의 이 섹션"이다. vault 조회 없이 앵커 링크가 된다.
+        if (!w.target) {
+            if (!slug)
+                return whole; // 블록 참조뿐 → 갈 곳이 없으므로 원문 보존
+            return `[${w.alias ?? w.fragment}](#${slug})`;
+        }
+        const found = resolve(w.target, w.embed);
         if (!found)
             return whole; // 해석 실패 → 원문 보존
-        const label = (alias ?? target).trim();
-        if (embed)
-            return `![${label}](${dest(found)})`;
-        // Obsidian 은 섹션을 헤딩 텍스트로 가리키지만(`#1. 신뢰 — Trust Registry`)
-        // 표준 마크다운은 슬러그를 쓴다. 블록 참조(`#^id`)는 대응물이 없어 링크만 남긴다.
-        const slug = hash ? wikilinkAnchorToSlug(hash.slice(1)) : null;
+        const label = w.alias ?? w.target;
+        if (w.embed)
+            return `![${label}](${dest(found + (/\.pdf$/i.test(w.target) && slug ? `#${slug}` : ''))})`;
         return `[${label}](${dest(found + (slug ? `#${slug}` : ''))})`;
     }));
 }

package/dist/pdf-pages.js

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { resolve, relative, dirname } from 'node:path';
+import { renderPdfPages } from './pdf-renderer.js';
+import MarkdownIt from 'markdown-it';
+import { collectHeadings } from './anchors.js';
+const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64');
+const decode = (value) => JSON.parse(Buffer.from(value, 'base64').toString());
+const parser = new MarkdownIt({ html: true });
+/** 소스 위치를 유지하면서 코드·HTML 블록을 제외한 일반 텍스트를 처리한다. */
+export function mapMarkdownText(text, fn) {
+    const lines = text.split('\n'), offsets = [0];
+    for (const line of lines)
+        offsets.push(offsets[offsets.length - 1] + line.length + 1);
+    const spans = parser.parse(text, {}).filter(t => ['fence', 'code_block', 'html_block'].includes(t.type) && t.map)
+        .map(t => [offsets[t.map[0]], Math.min(offsets[t.map[1]], text.length)]);
+    let cursor = 0, result = '';
+    const prose = (s) => protectInline(s, fn);
+    for (const [start, end] of spans) {
+        if (start < cursor)
+            continue;
+        result += prose(text.slice(cursor, start)) + text.slice(start, end);
+        cursor = end;
+    }
+    return result + prose(text.slice(cursor));
+}
+function protectInline(text, fn) {
+    const re = /(`+)([\s\S]*?)(?<!`)\1(?!`)/g;
+    let cursor = 0, out = '';
+    for (const m of text.matchAll(re)) {
+        out += fn(text.slice(cursor, m.index)) + m[0];
+        cursor = m.index + m[0].length;
+    }
+    return out + fn(text.slice(cursor));
+}
+const REF = /\[([^\]\n]*)\]\(#[^\s)]+\)<!-- csync-pdf:v1 ([A-Za-z0-9+/=]+) -->/g;
+const INLINE_REF = /!\[([^\]\n]*)\]\((?:<[^>\n]+>|[^()\s]+)\)<!-- csync-pdf-inline:v1 ([A-Za-z0-9+/=]+) -->/g;
+const GALLERY = /\n*<!-- csync-pdf-pages:v1 -->\n[\s\S]*?<!-- \/csync-pdf-pages -->\n*/g;
+/** 자동 생성한 참조만 복원한다. 일반 이미지·제목은 유지한다. */
+export function restorePdfReferences(text, file, base) {
+    const assets = [];
+    // 매크로 표식은 코드 예제에서 복원하지 않도록 실제 HTML 토큰만 검사한다.
+    const restore = (_all, currentLabel, data) => {
+        const ref = decode(data);
+        if (typeof ref.path !== 'string' || !/\.pdf$/i.test(ref.path) || !Number.isSafeInteger(ref.page) || ref.page < 1) {
+            throw new Error('PDF 역변환 정보의 경로 또는 쪽 번호가 올바르지 않습니다.');
+        }
+        const abs = resolve(dirname(file), ref.path);
+        requireLocal(abs, base);
+        if (!existsSync(abs))
+            throw new Error(`역변환에 필요한 원본 PDF가 없습니다: ${abs}`);
+        assets.push(abs);
+        const path = relative(base, abs).split('\\').join('/');
+        return `${ref.embed ? '!' : ''}[[${path}#page=${ref.page}|${currentLabel || ref.label}]]`;
+    };
+    const restored = replaceGeneratedBlocks(replaceGeneratedBlocks(text, INLINE_REF, restore), REF, restore);
+    return { text: replaceGeneratedBlocks(restored, GALLERY, () => '\n\n'), assets: [...new Set(assets)], pages: 0 };
+}
+/** 생성 표식을 처리하되 fenced/indented code는 그대로 보존한다. */
+export function replaceGeneratedBlocks(text, re, fn) {
+    const lines = text.split('\n'), offsets = [0];
+    for (const line of lines)
+        offsets.push(offsets[offsets.length - 1] + line.length + 1);
+    const spans = parser.parse(text, {}).filter(t => ['fence', 'code_block'].includes(t.type) && t.map)
+        .map(t => [offsets[t.map[0]], Math.min(offsets[t.map[1]], text.length)]);
+    for (const m of text.matchAll(/(`+)([\s\S]*?)(?<!`)\1(?!`)/g))
+        spans.push([m.index, m.index + m[0].length]);
+    return text.replace(re, (...args) => {
+        const offset = args[args.length - 2];
+        const markerOffset = offset + args[0].search(/\S/);
+        return spans.some(([s, e]) => markerOffset >= s && markerOffset < e) ? args[0] : fn(...args);
+    });
+}
+function requireLocal(abs, base) {
+    const rel = relative(realpathSync(base), existsSync(abs) ? realpathSync(abs) : abs);
+    if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\'))
+        throw new Error(`PDF는 --base 안에 있어야 합니다: ${abs}`);
+}
+export async function extractPdfPages(text, file, base, output, dryRun, source = p => p) {
+    const assets = new Set(), headings = new Set(collectHeadings(text).map(h => h.slug));
+    const pages = new Map();
+    const hashes = new Map();
+    const jobs = [];
+    const link = /(?<!!)(!?)\[([^\]\n]*)\]\((<[^>\n]+>|[^()\s]+)\)/g;
+    const convertLinks = (input, inline) => mapMarkdownText(input, part => part.replace(link, (all, bang, label, raw, offset) => {
+        // 홀수 개의 백슬래시로 이스케이프한 링크는 예제 텍스트다.
+        if ((part.slice(0, offset).match(/\\+$/)?.[0].length ?? 0) % 2)
+            return all;
+        let dest;
+        try {
+            dest = decodeURIComponent(raw.replace(/^<(.*)>$/, '$1'));
+        }
+        catch {
+            return all;
+        }
+        if (/^[a-z][a-z\d+.-]*:/i.test(dest))
+            return all;
+        const m = dest.match(/^(.*\.pdf)#page=(\d+)$/i);
+        if (!m)
+            return all;
+        const local = resolve(dirname(file), m[1]);
+        const abs = source(local);
+        if (abs === local)
+            requireLocal(local, base);
+        if (!existsSync(abs))
+            throw new Error(`PDF 파일을 찾을 수 없습니다: ${abs}`);
+        const page = Number(m[2]);
+        if (!Number.isSafeInteger(page) || page < 1)
+            throw new Error(`잘못된 PDF 쪽 번호: ${dest}`);
+        assets.add(abs);
+        let hash = hashes.get(abs);
+        if (!hash) {
+            hash = createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 24);
+            hashes.set(abs, hash);
+        }
+        const key = `${hash}-${page}`;
+        let entry = pages.get(key);
+        if (!entry) {
+            let heading = `PDF 원문 ${pages.size + 1} - ${page}쪽`;
+            let anchor = `pdf-원문-${pages.size + 1}---${page}쪽`, suffix = 0;
+            const initialHeading = heading, initialAnchor = anchor;
+            while (headings.has(anchor)) {
+                heading = `${initialHeading}-${++suffix}`;
+                anchor = `${initialAnchor}-${suffix}`;
+            }
+            headings.add(anchor);
+            const assetRel = `attachments/pdf-pages/pdfjs-${key}.png`;
+            const target = resolve(output, assetRel);
+            jobs.push({ file: abs, page, target });
+            const outputFile = resolve(output, relative(base, file));
+            const image = relative(dirname(outputFile), target).split('\\').join('/');
+            entry = { heading, anchor, image, gallery: false };
+            pages.set(key, entry);
+        }
+        const ref = { path: m[1], page, label, embed: bang === '!' };
+        if (inline)
+            return `![${label || `PDF ${page}쪽`}](<${entry.image}>)<!-- csync-pdf-inline:v1 ${encode(ref)} -->`;
+        entry.gallery = true;
+        return `[${label || `PDF ${page}쪽`}](#${entry.anchor})<!-- csync-pdf:v1 ${encode(ref)} -->`;
+    }));
+    const withInlineImages = replaceGeneratedBlocks(text, /<!-- csync-footnote:v1 [A-Za-z0-9+/=]+ -->\n[\s\S]*?<!-- \/csync-footnote -->/g, block => convertLinks(block, true));
+    const converted = convertLinks(withInlineImages, false);
+    if (!pages.size)
+        return { text, assets: restorePdfReferences(text, file, base).assets, pages: 0 };
+    await renderPdfPages(jobs, dryRun);
+    const gallery = [...pages.values()].filter(p => p.gallery).map(p => `### ${p.heading}\n\n![${p.heading}](<${p.image}>)`).join('\n\n');
+    return { text: converted.trimEnd() + (gallery ? `\n\n<!-- csync-pdf-pages:v1 -->\n${gallery}\n<!-- /csync-pdf-pages -->\n` : '\n'), assets: [...assets], pages: pages.size };
+}

package/dist/pdf-renderer.js

@@ -0,0 +1,63 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/** npm으로 설치한 렌더러와 글꼴/CMap/WASM 리소스만 사용한다. */
+export async function renderPdfPages(jobs, dryRun) {
+    if (!jobs.length)
+        return;
+    const { getDocument, VerbosityLevel } = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const { createCanvas } = await import('@napi-rs/canvas');
+    const require = createRequire(import.meta.url);
+    const root = dirname(require.resolve('pdfjs-dist/package.json'));
+    // PDF.js는 Windows에서도 '/'로 끝나는 리소스 경로를 요구한다.
+    const resourceDir = (name) => join(root, name).split('\\').join('/') + '/';
+    const files = new Map();
+    for (const job of jobs) {
+        const group = files.get(job.file) ?? [];
+        group.push(job);
+        files.set(job.file, group);
+    }
+    for (const [file, pages] of files) {
+        const task = getDocument({
+            data: new Uint8Array(readFileSync(file)),
+            cMapUrl: resourceDir('cmaps'),
+            cMapPacked: true,
+            standardFontDataUrl: resourceDir('standard_fonts'),
+            wasmUrl: resourceDir('wasm'),
+            useSystemFonts: false,
+            verbosity: VerbosityLevel.ERRORS,
+        });
+        try {
+            const pdf = await task.promise;
+            for (const { page } of pages) {
+                if (page > pdf.numPages)
+                    throw new Error(`PDF 쪽 범위 초과: ${page} (총 ${pdf.numPages}쪽)`);
+            }
+            if (dryRun)
+                continue;
+            for (const { page: pageNumber, target } of pages) {
+                if (existsSync(target))
+                    continue;
+                const page = await pdf.getPage(pageNumber);
+                const viewport = page.getViewport({ scale: 160 / 72 });
+                const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+                try {
+                    await page.render({ canvas: canvas, viewport }).promise;
+                    const png = await canvas.encode('png');
+                    mkdirSync(dirname(target), { recursive: true });
+                    writeFileSync(target, png);
+                }
+                finally {
+                    page.cleanup();
+                    canvas.width = canvas.height = 1;
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`PDF 이미지 변환 실패 (${file}): ${error.message}`);
+        }
+        finally {
+            await task.destroy();
+        }
+    }
+}

package/dist/pull.js

@@ -7,13 +7,18 @@
  * 함께 받은 페이지끼리의 내부 링크는 마지막에 상대 .md 경로로 이어 붙인다(Obsidian 그래프·백링크가 살아난다).
  * 각 문서 머리에 pageId 를 담은 frontmatter 를 남겨, 매핑 파일 없이도 push 가 원본 페이지를 다시 찾아간다.
  */
-import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { resolve, join, dirname, basename, relative } from 'node:path';
 import { readEnv, requireEnv } from './config.js';
 import { createClient } from './confluence.js';
 import { htmlToMarkdown, codeLanguagesFromStorage } from './html2md.js';
 import { buildFrontmatter, splitFrontmatter } from './obsidian.js';
 import { collectHeadings, matchConfluenceAnchor } from './anchors.js';
+import { collectMarkdown } from './docs.js';
+import { buildTreeRenderer } from './render.js';
+import { docHash } from './markdown.js';
+import { buildIgnorer } from './ignore.js';
+import { loadMapping, saveMapping, MAPPING_FILE } from './mapping.js';
 import { cyan, dim, green, red, yellow } from './colors.js';
 // 첨부 이미지는 항상 <md위치>/attachments/<문서명>/ 하위에 저장한다.
 const ASSETS_DIR = 'attachments';
@@ -112,6 +117,7 @@ async function pullNode(ctx, id, destDir) {
         if (node.type === 'folder') {
             const dir = join(destDir, slug(node.title));
             mkdirSync(dir, { recursive: true });
+            ctx.folderIds.set(dir, id);
             console.log(`  ${cyan('📁 폴더')}  ${dir}  ${dim(`(#${id})`)}`);
             const counts = { pages: 0, folders: 1 };
             if (withChildren) {
@@ -201,7 +207,7 @@ export function relinkPass(written, pathById, wikilinks, info) {
     let count = 0;
     for (const file of written) {
         const before = readFileSync(file, 'utf8');
-        const after = before.replace(PAGE_LINK, (whole, text, url, id) => {
+        let after = before.replace(PAGE_LINK, (whole, text, url, id) => {
             const target = pathById.get(id);
             if (!target || target === file)
                 return whole; // 못 받은 페이지·자기 자신 → 원본 URL 유지
@@ -219,15 +225,89 @@ export function relinkPass(written, pathById, wikilinks, info) {
             const rel = relative(dirname(file), target).split('\\').join('/');
             return `[${label}](${dest(rel + (slug ? `#${slug}` : ''))})`;
         });
+        // 같은 문서 섹션도 vault 표기로: [§4](#슬러그) → [[#헤딩 텍스트|§4]]
+        if (wikilinks) {
+            after = after.replace(SELF_ANCHOR, (whole, text, frag) => {
+                const heading = info?.get(file)?.textBySlug.get(frag);
+                if (!heading)
+                    return whole;
+                count++;
+                const label = text.trim();
+                return label && label !== heading ? `[[#${heading}|${label}]]` : `[[#${heading}]]`;
+            });
+        }
         if (after !== before)
             writeFileSync(file, after);
     }
     return count;
 }
+/**
+ * 매핑 파일(.confluence-sync.json)이 있는 가장 가까운 상위 디렉토리 = 동기화 루트.
+ * pull 을 base 하위 폴더로 받아도(`--out <base>/어딘가`) 매핑 키가 base 기준으로 남아야
+ * 이어지는 push 가 같은 문서를 알아본다.
+ */
+function findSyncBase(from) {
+    for (let d = from;; d = dirname(d)) {
+        if (existsSync(join(d, MAPPING_FILE)))
+            return d;
+        if (dirname(d) === d)
+            return null;
+    }
+}
+/**
+ * 받아온 문서를 매핑 파일에 기록한다.
+ *
+ * 이게 없으면 pull 직후의 push 가 모든 문서를 "변경"으로 본다 — 매핑에 해시가 없으니
+ * 방금 받아온 내용을 그대로 되올려 보내려 한다. 해시는 push 가 쓰는 것과 **같은 렌더러**로
+ * 계산해야 하므로(buildTreeRenderer) 트리 전체를 한 번 훑는다.
+ *
+ * 반환값은 기록한 항목 수.
+ */
+export function mappingPass(baseDir, mappingPath, pathById, folderIds) {
+    const posix = (p) => p.split('\\').join('/');
+    const ignorer = buildIgnorer(baseDir, []);
+    const rels = collectMarkdown(baseDir)
+        .map((f) => posix(relative(baseDir, f)))
+        .filter((r) => !ignorer.ignores(r));
+    const { docs, render } = buildTreeRenderer(baseDir, rels);
+    const m = loadMapping(mappingPath);
+    // 같은 페이지가 다른 키에 남아 있으면(문서가 옮겨졌으면) 중복 항목이 된다 → 옛 키를 걷어낸다
+    const ids = new Set([...pathById.keys(), ...folderIds.values()]);
+    for (const [k, v] of Object.entries(m))
+        if (ids.has(v.pageId))
+            delete m[k];
+    let n = 0;
+    for (const [id, abs] of pathById) {
+        const rel = posix(relative(baseDir, abs));
+        const doc = rel.startsWith('..') ? undefined : docs[rel];
+        if (!doc)
+            continue; // base 밖으로 받았거나 제외 규칙에 걸린 문서는 기록하지 않는다
+        m[rel] = { pageId: id, title: doc.title, hash: docHash(doc.title, render(rel, doc.body, doc.title)) };
+        n++;
+    }
+    for (const [dir, id] of folderIds) {
+        const rel = posix(relative(baseDir, dir));
+        if (!rel || rel.startsWith('..'))
+            continue;
+        m[`${rel}/`] = { pageId: id, title: basename(dir), type: 'folder' };
+        n++;
+    }
+    saveMapping(mappingPath, m);
+    return n;
+}
 export async function runPull(argv) {
     const withChildren = argv.includes('--children');
     const wholeSpace = argv.includes('--space');
     const outDir = resolve(optVal(argv, '--out') ?? process.cwd());
+    // 매핑을 어디에 남길지. base 는 매핑 키의 기준이므로 push 때의 --base 와 같아야 한다.
+    const noMapping = argv.includes('--no-mapping');
+    const baseOpt = optVal(argv, '--base');
+    const baseDir = resolve(baseOpt ?? findSyncBase(outDir) ?? outDir);
+    const mappingPath = resolve(optVal(argv, '--mapping') ?? join(baseDir, MAPPING_FILE));
+    if (!noMapping && relative(baseDir, outDir).startsWith('..')) {
+        console.error(red(`✗ --out 이 base 밖입니다: ${outDir}`) + dim(`\n  base: ${baseDir}  (--base 로 맞추거나 --no-mapping 을 쓰세요)`));
+        process.exit(1);
+    }
     const env = readEnv();
     requireEnv(env);
     const client = createClient({ baseUrl: env.baseUrl, email: env.email, token: env.token }, { force: false, verify: false });
@@ -238,14 +318,20 @@ export async function runPull(argv) {
         spaceKey: env.spaceKey,
         written: [],
         pathById: new Map(),
+        folderIds: new Map(),
     };
     const done = (c) => {
         // 앵커를 먼저 슬러그로 바꾼 뒤 링크를 상대경로로 옮긴다(순서가 바뀌면 어느 페이지의 헤딩인지 알 수 없다).
         const { count: anchors, info } = anchorPass(ctx.written, ctx.pathById);
         const relinked = relinkPass(ctx.written, ctx.pathById, ctx.obsidian, info);
+        // 본문이 다 정해진 뒤에 기록해야 해시가 맞는다
+        const mapped = noMapping ? 0 : mappingPass(baseDir, mappingPath, ctx.pathById, ctx.folderIds);
         console.log(`\n${green('완료')}  페이지 ${c.pages}개${c.folders ? `, 폴더 ${c.folders}개` : ''} 생성` +
             (relinked ? `  ${cyan(`내부링크 ${relinked}개 연결`)}` : '') +
-            (anchors ? `  ${cyan(`섹션링크 ${anchors}개 복원`)}` : ''));
+            (anchors ? `  ${cyan(`섹션링크 ${anchors}개 복원`)}` : '') +
+            (mapped ? `  ${cyan(`매핑 ${mapped}건`)}` : ''));
+        if (mapped)
+            console.log(dim(`  매핑: ${mappingPath}  (base: ${baseDir})`));
     };
     // --space: 스페이스 홈페이지(콘텐츠 트리 루트)부터 전체를 재귀적으로 가져옴
     if (wholeSpace) {
@@ -262,7 +348,7 @@ export async function runPull(argv) {
     // 위치 인자: ['pull', <pageId|url>, ...]
     const positionals = [];
     for (let i = 0; i < argv.length; i++) {
-        if (argv[i] === '--out') {
+        if (argv[i] === '--out' || argv[i] === '--base' || argv[i] === '--mapping') {
             i++;
             continue;
         }

package/dist/render.js

@@ -0,0 +1,27 @@
+/**
+ * 문서 트리 하나를 storage format 으로 옮기는 렌더러.
+ *
+ * 링크·섹션 링크는 **트리 전체**를 알아야 풀린다(다른 문서의 제목과 헤딩을 참조하므로),
+ * 그래서 문서 하나가 아니라 트리 단위로 만든다.
+ *
+ * push(sync)와 pull 의 매핑 기록이 **같은 문서에 같은 해시**를 내야 하므로 —
+ * 어긋나면 pull 직후 push 가 전부 "변경"으로 보인다 — 두 곳이 이 함수 하나를 함께 쓴다.
+ */
+import { relative } from 'node:path';
+import { toStorage } from './markdown.js';
+import { buildDocIndex, buildVault, collectAssets, vaultResolver, resolveAnchorTargets, } from './docs.js';
+export function buildTreeRenderer(baseDir, rels) {
+    const { titles, anchors, docs } = buildDocIndex(rels, baseDir);
+    // Obsidian [[wikilink]] 해석용 이름 인덱스
+    const vault = buildVault(rels, collectAssets(baseDir).map((f) => relative(baseDir, f)));
+    // 누가 어느 헤딩을 가리키는지 먼저 모은다 — 그 헤딩에만 Anchor 매크로를 심는다.
+    const anchorTargets = resolveAnchorTargets(docs, vault);
+    const render = (rel, body, title) => toStorage(body, rel, titles, baseDir, {
+        resolveLink: vaultResolver(rel, vault),
+        anchorIndex: anchors,
+        title,
+        anchorNames: anchorTargets[rel],
+        bodySlugs: docs[rel]?.bodySlugs,
+    });
+    return { titles, docs, render };
+}

package/dist/sync.js

@@ -17,8 +17,9 @@ import 'dotenv/config';
 import { existsSync, statSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { readEnv, requireEnv } from './config.js';
-import { toStorage, docHash } from './markdown.js';
-import { collectMarkdown, collectAssets, buildDocIndex, resolveAnchorTargets, buildFolderIndex, buildVault, vaultResolver, readDoc, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
+import { docHash } from './markdown.js';
+import { buildTreeRenderer } from './render.js';
+import { collectMarkdown, buildFolderIndex, readDoc, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
 import { loadMapping, saveMapping } from './mapping.js';
 import { createClient } from './confluence.js';
 import { runInit } from './init.js';
@@ -104,24 +105,13 @@ async function main() {
     if (!DRY_RUN && !LIST)
         requireEnv(env); // list/dry 는 Confluence 호출이 없어 인증 불필요
     const ignorer = buildIgnorer(BASE_DIR, EXCLUDES);
-    const collected = collectMarkdown(BASE_DIR).map((f) => relative(BASE_DIR, f));
+    const collected = collectMarkdown(BASE_DIR).map((f) => relative(BASE_DIR, f).split('\\').join('/'));
     const allRel = collected.filter((r) => !ignorer.ignores(r)); // 제외된 문서는 모든 단계에서 빠짐
     const ignoredCount = collected.length - allRel.length;
     const folderIndex = buildFolderIndex(allRel);
-    // 링크·섹션 링크 변환은 항상 전체 기준(선택 동기화여도 대상 문서의 제목·헤딩을 알아야 한다)
-    const { titles: titleIndex, anchors: anchorIndex, docs } = buildDocIndex(allRel, BASE_DIR);
-    // Obsidian [[wikilink]] 해석용 이름 인덱스. 제외된 문서는 링크 대상에서도 빠진다.
-    const vault = buildVault(allRel, collectAssets(BASE_DIR).map((f) => relative(BASE_DIR, f)));
-    // 누가 어느 헤딩을 가리키는지 먼저 모은다 — 그 헤딩에만 Anchor 매크로를 심는다.
-    // 선택 동기화여도 트리 전체를 봐야 한다(다른 문서가 이 문서의 섹션을 가리킬 수 있으므로).
-    const anchorTargets = resolveAnchorTargets(docs, vault);
-    const render = (rel, body, title) => toStorage(body, rel, titleIndex, BASE_DIR, {
-        resolveLink: vaultResolver(rel, vault),
-        anchorIndex,
-        title,
-        anchorNames: anchorTargets[rel],
-        bodySlugs: docs[rel]?.bodySlugs,
-    });
+    // 링크·섹션 링크 변환은 항상 트리 전체 기준이다. 선택 동기화여도 대상 문서의 제목·헤딩을 알아야 하고,
+    // 다른 문서가 이 문서의 섹션을 가리킬 수 있다. 제외된 문서는 링크 대상에서도 빠진다.
+    const { titles: titleIndex, render } = buildTreeRenderer(BASE_DIR, allRel);
     // 사용자가 실제로 고른 문서. 경로 인자가 없으면 전체가 대상이다.
     const picked = positionals.length ? resolveSelection(allRel, positionals, BASE_DIR) : allRel;
     const explicit = new Set(picked);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "type": "module",
   "description": "Confluence Cloud ↔ Markdown 양방향 동기화 CLI — 마크다운을 Confluence 페이지로 발행(push)하고, Confluence 페이지·폴더·스페이스를 마크다운으로 가져옵니다(pull).",
   "keywords": [
@@ -23,7 +23,7 @@
     "url": "https://github.com/wonseok-han/confluence-sync/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "bin": {
     "confluence-sync": "dist/sync.js",
@@ -36,23 +36,29 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "prepublishOnly": "npm run build",
     "sync": "tsx src/sync.ts",
     "sync:dry": "tsx src/sync.ts --dry-run",
     "sync:rebuild": "tsx src/sync.ts --rebuild",
-    "list": "tsx src/sync.ts --list"
+    "list": "tsx src/sync.ts --list",
+    "test:coverage": "npm run build && node --test --experimental-test-coverage --test-coverage-include=\"dist/**/*.js\" tests/*.test.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "@napi-rs/canvas": "^1.0.9",
     "dotenv": "^16.4.5",
     "ignore": "^7.0.5",
     "markdown-it": "^14.1.0",
+    "markdown-it-footnote": "^4.0.0",
+    "pdfjs-dist": "^6.3.289",
     "turndown": "^7.2.4"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",
+    "@types/markdown-it-footnote": "^3.0.4",
     "@types/node": "^22.0.0",
     "@types/turndown": "^5.0.6",
     "tsx": "^4.19.0",