@wonseok-han/confluence-sync 1.3.0 → 1.5.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` 로 바꿔 쓸 수 있습니다.
 
@@ -130,6 +130,7 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 
 - 페이지 제목은 **frontmatter `title` → 첫 `# 제목` → 파일명** 순으로 정해지고, 본문은 storage format 으로 변환됩니다.
 - 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
+- `mermaid` 코드블록 뒤에는 **Mermaid diagram** 매크로를 자동 삽입합니다. Confluence에 [Atlassian Labs Mermaid Diagrams Viewer](https://marketplace.atlassian.com/apps/1232887/mermaid-diagrams-viewer)가 설치되어 있어야 하며, 원본 코드도 함께 표시됩니다. 자동 연결은 등장 순서를 사용하므로 페이지의 모든 Mermaid 코드는 `mermaid` 코드블록으로 작성하세요.
 - **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
 - **섹션 링크** `[§1 개요](#1-개요)` · `[§6](./04-구현체.md#6-zkp)` · `[[문서#헤딩 텍스트]]` → Confluence 앵커 링크. [아래 참조](#섹션-링크-앵커)
 - **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
@@ -298,6 +299,15 @@ confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
 - **섹션 링크는 표기가 다릅니다** — 표준 마크다운은 슬러그(`문서.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`)
 
 변환기가 개선되기 전에 pull 한 문서에는 옛 결함의 흔적이 남아 있습니다. 스페이스를 통째로 다시 받지 않고 그 흔적만 되돌립니다.
@@ -334,6 +344,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/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,7 +75,7 @@ function commonAncestor(paths) {
  * wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 트리 안에서 유일할 때만 바꾼다
  * (겹치면 엉뚱한 노트로 이어질 수 있어 상대 링크를 그대로 둔다).
  */
-function toObsidian(text, fileAbs, baseDir, nameCount, headingOf, selfHeadingOf) {
+function toObsidian(text, fileAbs, baseDir, nameCount, headingOf, selfHeadingOf, source = p => p) {
     return linksToWikilinks(text, (dest, label) => {
         if (/^(https?:|mailto:)/i.test(dest))
             return null; // 외부 링크
@@ -76,6 +89,13 @@ function toObsidian(text, fileAbs, baseDir, nameCount, headingOf, selfHeadingOf)
             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);
@@ -167,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 를 직접 지목한 경우(예: 이웃 폴더 파일) 는 위 필터에 안 걸린다
@@ -189,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);
     }
@@ -204,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);
@@ -217,22 +239,60 @@ export async function runConvert(argv) {
             }
         }
         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()));
+            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}쪽 이미지`));
         }
-        else if (to === 'markdown')
-            text = resolveWikilinks(text, vaultResolver(rel, vault));
         // 제자리 변환이면 바뀐 것만 쓰지만, --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

@@ -219,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

@@ -63,6 +63,9 @@ ${h('pull(역방향) 옵션:')}
 ${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>')}     링크를 해석할 문서 트리 루트(기본: 준 경로들의 공통 상위 폴더)

package/dist/markdown.js

@@ -11,6 +11,7 @@ import { createHash } from 'node:crypto';
 import MarkdownIt from 'markdown-it';
 import { resolveWikilinks } from './obsidian.js';
 import { decodeAnchor, anchorMacro } from './anchors.js';
+import { mermaidMacro } from './mermaid.js';
 export const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 export const hashOf = (s) => createHash('sha256').update(s).digest('hex');
 /** markdown-it 이 퍼센트 인코딩한 링크/이미지 경로를 실제 경로로 디코드(실패 시 원본). */
@@ -25,7 +26,7 @@ const decodePath = (s) => {
 const md = new MarkdownIt({ html: true, linkify: true, breaks: false });
 const emptyCtx = () => ({
     fileDir: '', titleIndex: {}, anchorIndex: {}, selfRel: '', selfTitle: '',
-    anchorNames: new Set(), bodySlugs: [], headingSeq: 0, anchorsPlaced: 0,
+    anchorNames: new Set(), bodySlugs: [], headingSeq: 0, mermaidSeq: 0, anchorsPlaced: 0,
     images: [], internalLinks: 0, anchorLinks: 0, deadAnchors: [], linkStack: [], linkedTitles: new Set(),
 });
 // 렌더 규칙은 md 인스턴스에 한 번만 등록되므로, 현재 변환 컨텍스트를 모듈 변수로 공유한다.
@@ -57,7 +58,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;
@@ -76,10 +77,19 @@ 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];
+    const infoLang = (t.info || '').trim().split(/\s+/)[0];
+    const lang = infoLang.toLowerCase() === 'mermaid' ? 'mermaid' : infoLang;
+    // 별도 호스팅한 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`;
+    const langParam = lang ? `<ac:parameter ac:name="language">${escapeXml(lang)}</ac:parameter>` : '';
+    const code = `<ac:structured-macro ac:name="code">${langParam}<ac:plain-text-body><![CDATA[${safe}]]></ac:plain-text-body></ac:structured-macro>\n`;
+    return code + (lang === 'mermaid' ? mermaidMacro(ctx.selfRel, ctx.mermaidSeq++) : '');
 };
 md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
     const href = tokens[idx].attrGet('href') || '';

package/dist/mermaid.js

@@ -0,0 +1,13 @@
+import { createHash } from 'node:crypto';
+// Atlassian Labs Mermaid Diagrams Viewer (Marketplace production deployment).
+// Confirmed against the installed macro's editor/clipboard attributes.
+export const MERMAID_EXTENSION_KEY = '23392b90-4271-4239-98ca-a3e96c663cbb/63d4d207-ac2f-4273-865c-0240d37f044a/static/mermaid-diagram';
+/** Auto-detect pairs Mermaid code blocks and viewer macros in document order. */
+export function mermaidMacro(document, ordinal) {
+    // Random IDs would change the storage hash on every push. Include the ordinal
+    // so repeated identical diagrams still have distinct macro instances.
+    const hex = createHash('sha256').update(`csync:mermaid:${document}:${ordinal}`).digest('hex');
+    const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+    const node = `<ac:adf-node type="extension"><ac:adf-attribute key="extension-type">com.atlassian.ecosystem</ac:adf-attribute><ac:adf-attribute key="extension-key">${MERMAID_EXTENSION_KEY}</ac:adf-attribute><ac:adf-attribute key="parameters"><ac:adf-parameter key="local-id">${id}</ac:adf-parameter><ac:adf-parameter key="extension-id">ari:cloud:ecosystem::extension/${MERMAID_EXTENSION_KEY}</ac:adf-parameter><ac:adf-parameter key="extension-title">Mermaid diagram</ac:adf-parameter></ac:adf-attribute><ac:adf-attribute key="text">Mermaid diagram</ac:adf-attribute><ac:adf-attribute key="layout">default</ac:adf-attribute><ac:adf-attribute key="local-id">${id}</ac:adf-attribute></ac:adf-node>`;
+    return `<ac:adf-extension>${node}<ac:adf-fallback>${node}</ac:adf-fallback></ac:adf-extension>\n`;
+}

package/dist/obsidian.js

@@ -73,7 +73,9 @@ export function resolveWikilinks(md, resolve) {
             return whole;
         // Obsidian 은 섹션을 헤딩 텍스트로 가리키지만(`#1. 신뢰 — Trust Registry`)
         // 표준 마크다운은 슬러그를 쓴다. 블록 참조(`#^id`)는 대응물이 없어 섹션을 떼어 낸다.
-        const slug = w.fragment ? wikilinkAnchorToSlug(w.fragment) : null;
+        const slug = w.fragment
+            ? (/\.pdf$/i.test(w.target) ? w.fragment : wikilinkAnchorToSlug(w.fragment))
+            : null;
         // [[#헤딩]] — 대상이 없으면 "이 문서의 이 섹션"이다. vault 조회 없이 앵커 링크가 된다.
         if (!w.target) {
             if (!slug)
@@ -85,7 +87,7 @@ export function resolveWikilinks(md, resolve) {
             return whole; // 해석 실패 → 원문 보존
         const label = w.alias ?? w.target;
         if (w.embed)
-            return `![${label}](${dest(found)})`;
+            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/sync.js

@@ -105,7 +105,7 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.3.0",
+  "version": "1.5.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",