@wonseok-han/confluence-sync 1.1.0 → 1.2.0

package/README.md

@@ -129,9 +129,36 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 - 페이지 제목은 **frontmatter `title` → 첫 `# 제목` → 파일명** 순으로 정해지고, 본문은 storage format 으로 변환됩니다.
 - 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
 - **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
+- **섹션 링크** `[§1 개요](#1-개요)` · `[§6](./04-구현체.md#6-zkp)` · `[[문서#헤딩 텍스트]]` → Confluence 앵커 링크. [아래 참조](#섹션-링크-앵커)
 - **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
 - **YAML frontmatter** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
 
+### 섹션 링크 (앵커)
+
+문서는 표준 마크다운 그대로 두면 됩니다. 이 도구가 Confluence 쪽 앵커를 만들어 맞춰 줍니다.
+
+**Confluence 가 헤딩에 자동으로 붙이는 id 에는 기대지 않습니다.** 그 규칙은 Cloud 와 Data Center 가 다르고(Cloud 는 공백만 하이픈으로 바꾸고, DC 는 `페이지제목-헤딩` 형태) 예고 없이 바뀌기 때문입니다. 대신 **링크 대상이 되는 헤딩 앞에 [Anchor 매크로](https://confluence.atlassian.com/doc/anchors-139442.html)로 이름(= 마크다운 슬러그)을 직접 심고** 링크가 그 이름을 가리키게 합니다 — 양쪽 다 이 도구가 정한 값이라 어느 배포판에서도 맞습니다. 실제로 가리켜지는 헤딩에만 심으므로 페이지가 지저분해지지 않습니다.
+
+| 쓰는 것 | Confluence 에서 |
+| --- | --- |
+| `[§1 개요](#1-개요)` | 같은 페이지의 그 헤딩으로 이동 |
+| `[§6 ZKP](./04-구현체.md#6-zkp)` | 그 페이지의 그 헤딩으로 이동 |
+| `[[04-구현체#6. ZKP]]` | 위와 동일 (Obsidian 표기) |
+
+- 슬러그 규칙은 **GitHub 과 동일**합니다 — 소문자화 → 문자·숫자 아닌 것 제거 → 공백 하나당 하이픈 하나. 공백을 접지 않으므로 `제목  ·  블록` 의 `--` 도 그대로 맞습니다. 겹치는 헤딩에는 `-1`·`-2` 가 붙습니다.
+- 문서의 첫 `# H1` 을 가리키는 링크는 **페이지 최상단**이 됩니다 (H1 은 Confluence 페이지 제목이 되므로).
+- **대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 경고합니다.** 엉뚱한 섹션으로 보내는 대신 알려주는 쪽을 택했습니다 — 대개 오타나 깨진 상대경로입니다.
+
+```
+$ confluence-sync --base ./docs --dry-run
+  [변경] core-tech/03-standards.md  →  "표준 참조"  (…, 내부링크: 36, 섹션링크: 30, 앵커: 15, 이미지: 0)
+  ⚠ 대응 헤딩 없는 앵커  poc/02-zkp/legacy/README.md  #부록-a-개념-다리
+```
+
+`섹션링크` 는 이 문서가 **가리키는** 링크 수, `앵커` 는 이 문서에 **심긴** 앵커 수입니다(다른 문서가 가리키는 것 포함).
+
+pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니다(`--obsidian` 이면 `[[문서#헤딩 텍스트]]`).
+
 ### 변경 감지와 매핑
 
 - 문서의 `제목 + 본문 + 참조 이미지 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
@@ -175,6 +202,7 @@ confluence-sync pull --space --obsidian --out ~/MyVault   # 내부 링크를 [[w
 - **`--space`** — 대상 없이 스페이스 전체를 가져옵니다. 페이지가 많으면 시간이 걸립니다.
 - **이미지/첨부** 는 문서별로 `attachments/<문서명>/` 아래에 내려받고 링크를 그 경로로 씁니다 (문서 폴더가 이미지로 지저분해지지 않음). 다운로드에는 `read:attachment` 스코프가 필요합니다.
 - **내부 링크** 는 같은 실행에서 함께 받은 페이지끼리 **상대 `.md` 링크로 이어집니다.** 받지 않은 페이지는 절대 URL 로 남습니다(깨진 링크를 만들지 않음).
+- **섹션 링크** 는 Confluence 앵커(`#페이지제목헤딩텍스트`)를 그 문서의 **마크다운 슬러그로 되돌립니다** — 그대로 두면 Obsidian·GitHub 어디서도 걸리지 않기 때문입니다. `--obsidian` 이면 `[[문서#헤딩 텍스트]]` 로 씁니다.
 - 각 문서 머리에 **frontmatter** 가 붙습니다 — `title` · `pageId` · `spaceKey` · `source` · `updated`. `pageId` 가 다시 push 할 때의 앵커입니다.
 - 제목은 frontmatter 의 `title` 로만 들어가고 **본문에 `# 제목` 을 따로 넣지 않습니다** — 제목을 별도로 표시하는 뷰어(Obsidian 등)에서 두 번 보이기 때문입니다. push 는 `title` 을 먼저 읽으므로 왕복에 문제가 없습니다.
 - 본문은 `export_view`(HTML)를 [turndown](https://github.com/mixmark-io/turndown) 으로 변환합니다 — 코드블록(언어 포함, 미지정은 `plaintext`), GFM 표, 리스트 등.
@@ -244,6 +272,7 @@ confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
 - 외부 URL·이미지·깨진 링크(대상 파일 없음)는 **그대로 둡니다.**
 - 파일명이 트리 안에서 겹치면(`README.md` 여러 개 등) `[[wikilink]]` 로 바꾸지 않고 상대 링크를 유지합니다 — 이름만으로는 어느 노트인지 확정할 수 없기 때문입니다.
 - 코드블록·인라인 코드 안의 링크는 손대지 않습니다.
+- **섹션 링크는 표기가 다릅니다** — 표준 마크다운은 슬러그(`문서.md#6-zkp`), Obsidian 은 헤딩 텍스트(`[[문서#6. ZKP]]`)를 씁니다. 대상 문서의 헤딩을 찾아 옮기고, 못 찾으면 섹션 없이 문서 링크로 둡니다. Obsidian 블록 참조(`#^id`)는 마크다운에 대응물이 없어 같은 방식으로 처리합니다.
 
 ### 보정 (`--fix`)
 

package/dist/anchors.js

@@ -0,0 +1,157 @@
+/**
+ * 헤딩 앵커 — 마크다운과 Confluence 의 서로 다른 "섹션 가리키기" 표기를 잇는다.
+ *
+ *   마크다운(GitHub·Obsidian·VS Code)   [§1](#1-신뢰--trust-registry----블록-01)   ← 슬러그
+ *   Obsidian wikilink                   [[문서#1. 신뢰 — Trust Registry  ·  블록 01]]  ← 헤딩 텍스트
+ *
+ * **Confluence 가 헤딩에 자동으로 붙이는 id 에는 기대지 않는다.** 그 규칙은 Cloud 와 Data Center 가
+ * 서로 다르고(‑ Cloud 는 공백만 하이픈으로 바꾸고, DC 는 `페이지제목-헤딩` 형태다) 예고 없이 바뀐다.
+ * 대신 링크 대상이 되는 헤딩 앞에 **Anchor 매크로로 이름을 직접 심고**, 링크는 그 이름을 가리킨다.
+ * 이름은 마크다운 슬러그를 그대로 쓰므로 왕복도 정확해진다 — 양쪽 다 우리가 정한 값이다.
+ */
+const FENCE = /^\s*(?:```|~~~)/;
+/** 인라인 마크다운 표기를 벗긴다 — 슬러그는 렌더된 텍스트 기준이다. */
+function plainText(s) {
+    return s
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // [label](url) → label
+        .replace(/\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|([^\]]+))?\]\]/g, (_m, t, a) => a ?? t)
+        .replace(/`+/g, '')
+        .replace(/\*\*|~~|\*/g, '') // _ 는 남긴다: 슬러그가 밑줄을 보존하므로(foo_bar → foo_bar)
+        .trim();
+}
+/**
+ * GitHub 호환 헤딩 슬러그: 소문자 → 문자·숫자·공백·하이픈·밑줄 외 제거 → 공백 하나당 하이픈 하나.
+ * 공백을 **접지 않는** 것이 핵심이다 — `제목  ·  블록` 처럼 구두점이 빠지면 하이픈이 여러 개 남는다.
+ */
+export function slugifyHeading(text) {
+    return plainText(text)
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+/** 본문의 ATX 헤딩 목록(코드블록 안은 제외). 슬러그가 겹치면 GitHub 처럼 -1·-2 를 붙인다. */
+export function collectHeadings(md) {
+    const out = [];
+    const used = new Map();
+    let inFence = false;
+    for (const line of md.split('\n')) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        // 닫는 # 는 앞에 공백이 있을 때만 장식이다(`## C#` 의 # 를 지우지 않도록)
+        const m = line.match(/^(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/);
+        if (!m)
+            continue;
+        const text = m[2].trim();
+        if (!text)
+            continue;
+        const base = slugifyHeading(text);
+        const n = used.get(base) ?? 0;
+        used.set(base, n + 1);
+        out.push({ text, slug: n ? `${base}-${n}` : base, level: m[1].length });
+    }
+    return out;
+}
+/** 슬러그 → 헤딩 텍스트. 먼저 나온 헤딩이 이긴다. */
+export function buildAnchorIndex(md) {
+    const idx = new Map();
+    for (const h of collectHeadings(md))
+        if (!idx.has(h.slug))
+            idx.set(h.slug, h.text);
+    return idx;
+}
+/** 퍼센트 인코딩된 앵커를 되돌린다(실패하면 원문). */
+export const decodeAnchor = (s) => {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+};
+/**
+ * Confluence 앵커 비교용 키 — 공백·구두점을 모두 지운 소문자.
+ * Confluence 는 헤딩 앵커 id 를 만들 때 공백을 지우고 구두점 처리도 버전마다 달라서,
+ * 남는 글자(문자·숫자)만으로 맞춰야 안정적이다.
+ */
+export const anchorKey = (s) => s.normalize('NFC').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
+/**
+ * Confluence 가 만든 앵커 fragment 를 이 문서의 헤딩에 맞춘다.
+ * id 는 보통 `<페이지제목><헤딩텍스트>`(공백 제거) 형태라 제목 접두사를 허용하고,
+ * 그래도 안 맞으면 "헤딩으로 끝나는가"로 한 번 더 시도한다(가장 긴 헤딩이 이긴다).
+ */
+export function matchConfluenceAnchor(fragment, headings, pageTitle) {
+    const frag = anchorKey(decodeAnchor(fragment));
+    if (!frag)
+        return null;
+    const titleKey = anchorKey(pageTitle);
+    let loose = null;
+    let looseLen = 0;
+    for (const h of headings) {
+        const hk = anchorKey(h.text);
+        if (!hk)
+            continue;
+        if (frag === hk || frag === titleKey + hk)
+            return h; // 정확히 맞으면 바로
+        if (frag.endsWith(hk) && hk.length > looseLen) {
+            loose = h;
+            looseLen = hk.length;
+        }
+    }
+    return loose;
+}
+/**
+ * Obsidian wikilink 의 앵커(`[[문서#헤딩 텍스트]]`)를 마크다운 슬러그로.
+ * 중첩 헤딩(`#상위#하위`)은 마지막 것이 실제 목적지고, 블록 참조(`#^id`)는 마크다운에 대응물이 없다.
+ */
+export function wikilinkAnchorToSlug(anchor) {
+    const last = anchor.split('#').filter(Boolean).pop();
+    if (!last || last.startsWith('^'))
+        return null;
+    return slugifyHeading(last) || null;
+}
+const MD_LINK = /\[([^\]]*)\]\((<[^>]+>|[^()\s]+)\)/g;
+const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
+/**
+ * 본문에서 **앵커가 붙은 링크만** 훑는다 — 어느 문서의 어느 헤딩에 앵커를 심어야 하는지 알아내기 위해서다.
+ * 전체 렌더보다 훨씬 싸고, 코드블록·인라인 코드·이미지는 제외한다.
+ */
+export function collectLinkAnchors(md) {
+    const out = [];
+    let inFence = false;
+    for (const line of md.split('\n')) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        // 홀수 인덱스 = 인라인 코드 → 링크로 치지 않는다
+        const prose = line.split(/(`+[^`]*`+)/).filter((_, i) => i % 2 === 0).join('');
+        for (const m of prose.matchAll(MD_LINK)) {
+            if (prose[m.index - 1] === '!')
+                continue; // 이미지
+            const d = decodeAnchor(m[2].replace(/^<(.*)>$/, '$1'));
+            const i = d.indexOf('#');
+            if (i < 0 || i === d.length - 1)
+                continue;
+            if (/^(https?:|mailto:)/i.test(d))
+                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])
+                continue; // 임베드·앵커 없는 wikilink
+            out.push({ dest: m[2].trim(), fragment: m[3].slice(1), wiki: true });
+        }
+    }
+    return out;
+}
+/** Anchor 매크로 — 링크 대상 헤딩 바로 앞에 심어 이름을 고정한다. */
+export function anchorMacro(name) {
+    const safe = name.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">${safe}</ac:parameter></ac:structured-macro>`;
+}

package/dist/convert.js

@@ -12,7 +12,8 @@
 import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
 import { resolve, relative, dirname, basename, join } from 'node:path';
 import { collectMarkdown, collectAssets, buildVault, vaultResolver } from './docs.js';
-import { linksToWikilinks, resolveWikilinks } from './obsidian.js';
+import { linksToWikilinks, resolveWikilinks, splitFrontmatter } from './obsidian.js';
+import { buildAnchorIndex } from './anchors.js';
 import { repairMarkdown, totalFixes } from './repair.js';
 import { bold, cyan, dim, gray, green, red, yellow } from './colors.js';
 function optVal(argv, name) {
@@ -61,10 +62,10 @@ function commonAncestor(paths) {
  * wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 트리 안에서 유일할 때만 바꾼다
  * (겹치면 엉뚱한 노트로 이어질 수 있어 상대 링크를 그대로 둔다).
  */
-function toObsidian(text, fileAbs, baseDir, nameCount) {
+function toObsidian(text, fileAbs, baseDir, nameCount, headingOf) {
     return linksToWikilinks(text, (dest, label) => {
         if (/^(https?:|mailto:|#)/i.test(dest))
-            return null; // 외부 링크·앵커
+            return null; // 외부 링크·같은 문서 앵커
         const [pathPart, ...hash] = decode(dest).split('#');
         if (!/\.md$/i.test(pathPart))
             return null;
@@ -76,9 +77,13 @@ function toObsidian(text, fileAbs, baseDir, nameCount) {
         const name = basename(targetAbs).replace(/\.md$/i, '');
         if (nameCount.get(name) !== 1)
             return null; // 이름이 겹치면 상대 링크 유지
-        const anchor = hash.length ? `#${hash.join('#')}` : '';
+        // Obsidian 의 섹션 링크는 슬러그가 아니라 헤딩 텍스트다. 대상 문서에서 헤딩을 못 찾으면
+        // 슬러그를 그대로 넣어봤자 안 걸리므로, 링크는 살리되 섹션은 떼고 문서 최상단으로 보낸다.
+        const slug = hash.join('#');
+        const heading = slug ? headingOf(targetAbs, slug) : undefined;
+        const anchor = heading ? `#${heading}` : '';
         const l = label.trim();
-        return l && l !== name ? `[[${name}${anchor}|${l}]]` : `[[${name}${anchor}]]`;
+        return l && l !== name ? `[[${name}${anchor}|${l}]]` : anchor ? `[[${name}${anchor}|${name}]]` : `[[${name}]]`;
     });
 }
 export async function runConvert(argv) {
@@ -139,6 +144,16 @@ export async function runConvert(argv) {
         const n = basename(f).replace(/\.md$/i, '');
         nameCount.set(n, (nameCount.get(n) ?? 0) + 1);
     }
+    // 섹션 링크(#슬러그 ↔ #헤딩 텍스트)를 옮기려면 대상 문서의 헤딩을 알아야 한다. 필요할 때만 읽는다.
+    const anchorCache = new Map();
+    const headingOf = (targetAbs, slug) => {
+        let idx = anchorCache.get(targetAbs);
+        if (!idx) {
+            idx = buildAnchorIndex(splitFrontmatter(readFileSync(targetAbs, 'utf8')).body);
+            anchorCache.set(targetAbs, idx);
+        }
+        return idx.get(slug.toLowerCase());
+    };
     // 실제로 고쳐 쓸 파일(선택). 경로를 안 주면 base 전체.
     const selected = targets.length
         ? allMd.filter((f) => targets.some((t) => {
@@ -193,7 +208,7 @@ export async function runConvert(argv) {
             }
         }
         if (to === 'obsidian')
-            text = toObsidian(text, abs, baseDir, nameCount);
+            text = toObsidian(text, abs, baseDir, nameCount, headingOf);
         else if (to === 'markdown')
             text = resolveWikilinks(text, vaultResolver(rel, vault));
         // 제자리 변환이면 바뀐 것만 쓰지만, --out 이면 대상 전부를 내보낸다(온전한 트리가 나와야 하므로)

package/dist/docs.js

@@ -6,6 +6,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { join, resolve, relative, basename, dirname } from 'node:path';
 import { splitTitleAndBody } from './markdown.js';
 import { splitFrontmatter } from './obsidian.js';
+import { buildAnchorIndex, collectHeadings, collectLinkAnchors, wikilinkAnchorToSlug, decodeAnchor, } from './anchors.js';
 /**
  * 숨김 디렉토리는 문서가 아니다. Obsidian vault 의 `.obsidian/`(설정)·`.trash/`(휴지통) 과
  * `.git/`·`node_modules/` 가 여기서 걸러진다.
@@ -35,22 +36,85 @@ export function collectMarkdown(dir) {
 export function collectAssets(dir) {
     return walk(dir, (n) => !isMd(n));
 }
-/**
- * 문서 1건을 읽어 제목·본문·frontmatter 로 분해한다.
- * 제목 우선순위: frontmatter `title` > 첫 H1 > 파일명. H1 은 어느 경우든 본문에서 제거된다
- * (Confluence 는 페이지 제목을 따로 가지므로 본문에 남으면 제목이 두 번 보인다).
- */
 export function readDoc(baseDir, rel) {
     const { data, body: afterFm } = splitFrontmatter(readFileSync(resolve(baseDir, rel), 'utf8'));
+    // 앵커 사전은 H1 을 **포함해** 만든다 — GitHub 이 중복 슬러그에 -1·-2 를 붙이는 순서와 맞추기 위해서다.
+    // (H1 자체를 가리키는 링크는 Confluence 에서 페이지 최상단이 된다)
+    const all = collectHeadings(afterFm);
+    const anchors = buildAnchorIndex(afterFm);
     const { title, body } = splitTitleAndBody(afterFm, basename(rel).replace(/\.md$/i, ''));
-    return { title: (data.title || title).trim(), body, fm: data };
+    // splitTitleAndBody 가 본문에서 첫 H1 을 지우므로 슬러그 목록에서도 같은 것을 뺀다
+    const dropped = all.findIndex((h) => h.level === 1);
+    return {
+        title: (data.title || title).trim(),
+        body,
+        fm: data,
+        anchors,
+        bodySlugs: all.filter((_, i) => i !== dropped).map((h) => h.slug),
+        linkAnchors: collectLinkAnchors(afterFm),
+    };
 }
-/** base 상대 경로 → 문서 제목 인덱스 */
-export function buildTitleIndex(rels, baseDir) {
-    const idx = {};
-    for (const rel of rels)
-        idx[rel] = readDoc(baseDir, rel).title;
-    return idx;
+/** base 상대 경로 → 제목·앵커 인덱스(링크와 섹션 링크를 해석하는 데 둘 다 필요하다) */
+export function buildDocIndex(rels, baseDir) {
+    const titles = {};
+    const anchors = {};
+    const docs = {};
+    for (const rel of rels) {
+        const doc = readDoc(baseDir, rel);
+        titles[rel] = doc.title;
+        anchors[rel] = doc.anchors;
+        docs[rel] = doc;
+    }
+    return { titles, anchors, docs };
+}
+/** `a/b/../c.md` 같은 상대 이동을 정리해 base 상대 경로로 만든다. */
+function normalizeRel(dir, dest) {
+    const parts = (dir ? `${dir}/${dest}` : dest).split('/');
+    const out = [];
+    for (const p of parts) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..') {
+            if (!out.length)
+                return null; // base 밖
+            out.pop();
+        }
+        else
+            out.push(p);
+    }
+    return out.join('/');
+}
+/**
+ * 어느 문서의 어느 헤딩이 **실제로 링크 대상인지** 모은다.
+ * Confluence 가 헤딩에 붙이는 id 에 기대지 않고 Anchor 매크로로 이름을 심을 것이므로,
+ * 심을 곳을 알아야 한다. 아무도 가리키지 않는 헤딩에는 매크로를 넣지 않는다(페이지를 깨끗하게 유지).
+ */
+export function resolveAnchorTargets(docs, vault) {
+    const out = {};
+    for (const [rel, doc] of Object.entries(docs)) {
+        const dir = dirname(rel) === '.' ? '' : dirname(rel);
+        for (const la of doc.linkAnchors) {
+            let target;
+            let slug;
+            if (la.wiki) {
+                target = vault.notes[la.dest.toLowerCase().replace(/\.md$/i, '')] ?? null;
+                slug = wikilinkAnchorToSlug(la.fragment);
+            }
+            else {
+                target = la.dest === '' ? rel : normalizeRel(dir, decodeAnchor(la.dest));
+                if (target && !/\.md$/i.test(target))
+                    target = null;
+                slug = decodeAnchor(la.fragment).toLowerCase();
+            }
+            if (!target || !slug)
+                continue;
+            // 실제로 존재하는 헤딩만 — 없는 앵커는 markdown.ts 가 경고로 잡는다
+            if (!docs[target]?.anchors.has(slug))
+                continue;
+            (out[target] ??= new Set()).add(slug);
+        }
+    }
+    return out;
 }
 /**
  * wikilink 대상 이름 → base 상대 경로 인덱스.

package/dist/help.js

@@ -67,12 +67,20 @@ ${h('convert(이미 받아둔 .md 손보기) 옵션:')} ${dim('Confluence 호출
        ${o('confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault')}
        ${o('confluence-sync convert --fix ./docs/가이드/설치.md --base ./docs')}  ${dim('(파일 하나만)')}
 
+${h('섹션 링크(앵커):')}
+  ${o('[§1 개요](#1-개요)')} 처럼 헤딩을 가리키는 링크가 Confluence 에서도 동작합니다.
+  같은 문서(${o('#슬러그')})·다른 문서(${o('문서.md#슬러그')})·Obsidian(${o('[[문서#헤딩]]')}) 모두 지원합니다.
+  Confluence 의 자동 헤딩 id 는 배포판마다 달라서, 가리켜지는 헤딩 앞에 ${dim('Anchor 매크로')}로
+  이름을 직접 심고 그 이름을 가리킵니다. pull 은 반대로 슬러그를 되돌립니다.
+  대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 ${dim('⚠ 대응 헤딩 없는 앵커')} 로 알려 줍니다
+  ${dim('(대개 문서 쪽 오타나 깨진 상대경로입니다)')}.
+
 ${h('Obsidian:')}
   pull 결과는 vault 에서 바로 열립니다. 함께 받은 페이지끼리의 내부 링크가 이어져 그래프·백링크가
   동작하고, 각 문서의 frontmatter 에 pageId 가 남아 원본 페이지를 가리킵니다.
   [[wikilink]] 표기를 원하면 ${o('pull --obsidian')}, 이미 받아둔 문서라면 ${o('convert --to obsidian')}.
 
-  push 는 vault 문법을 그대로 이해합니다: ${o('[[wikilink]]')} · ${o('![[embed]]')} · YAML frontmatter
+  push 는 vault 문법을 그대로 이해합니다: ${o('[[wikilink]]')} · ${o('![[embed]]')} · ${o('[[문서#헤딩]]')} · YAML frontmatter
   (frontmatter 의 ${o('title')} 이 페이지 제목이 되고, ${o('pageId')} 가 있으면 매핑이 없어도 그 페이지를 갱신합니다).
 
 ${h('설정(.env):')}

package/dist/markdown.js

@@ -10,6 +10,7 @@ import { resolve, relative, dirname, basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import MarkdownIt from 'markdown-it';
 import { resolveWikilinks } from './obsidian.js';
+import { decodeAnchor, anchorMacro } from './anchors.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 이 퍼센트 인코딩한 링크/이미지 경로를 실제 경로로 디코드(실패 시 원본). */
@@ -22,19 +23,57 @@ 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,
+    images: [], internalLinks: 0, anchorLinks: 0, deadAnchors: [], linkStack: [], linkedTitles: new Set(),
+});
 // 렌더 규칙은 md 인스턴스에 한 번만 등록되므로, 현재 변환 컨텍스트를 모듈 변수로 공유한다.
-let ctx = { fileDir: '', titleIndex: {}, images: [], internalLinks: 0, linkStack: [], linkedTitles: new Set() };
+let ctx = emptyCtx();
 let baseDir = '';
-/** 링크 href 가 base 내부 .md 면 그 페이지 제목 반환 */
+/**
+ * 링크가 가리킬 앵커 이름을 정한다 — **슬러그를 그대로 쓴다.**
+ * 대상 헤딩 앞에 같은 이름의 Anchor 매크로가 심기므로 Confluence 의 자동 id 규칙과 무관하게 맞는다.
+ * 그 문서의 H1 은 Confluence 페이지 제목이 되므로 앵커가 아니라 '최상단'이다.
+ */
+function anchorOf(rel, fragment, pageTitle) {
+    const slug = decodePath(decodeAnchor(fragment)).toLowerCase();
+    const heading = ctx.anchorIndex[rel]?.get(slug);
+    if (!heading) {
+        ctx.deadAnchors.push(`#${slug}`); // 경고에 쓰이므로 사람이 읽을 수 있는 형태로 남긴다
+        return null;
+    }
+    return heading === pageTitle ? null : slug;
+}
+/** 링크 href 를 Confluence 내부 링크(페이지·앵커)로 해석. 아니면 null. */
 function resolveInternalLink(href) {
-    if (!href || /^(https?:|mailto:|#)/i.test(href))
+    if (!href || /^(https?:|mailto:)/i.test(href))
         return null;
-    const pathPart = href.split('#')[0];
+    // 같은 문서 안의 섹션: #슬러그
+    if (href.startsWith('#')) {
+        const anchor = anchorOf(ctx.selfRel, href.slice(1), ctx.selfTitle);
+        return anchor ? { title: null, anchor } : null;
+    }
+    const [pathPart, ...rest] = href.split('#');
     if (!pathPart || !/\.md$/i.test(pathPart))
         return null;
     const rel = relative(baseDir, resolve(baseDir, ctx.fileDir, decodePath(pathPart)));
-    return ctx.titleIndex[rel] ?? null;
+    const title = ctx.titleIndex[rel];
+    if (!title)
+        return null;
+    const fragment = rest.join('#');
+    return { title, anchor: fragment ? anchorOf(rel, fragment, title) : null };
 }
+// 링크 대상이 되는 헤딩 바로 앞에 Anchor 매크로를 심어 이름(슬러그)을 고정한다.
+// Confluence 가 헤딩에 붙이는 자동 id 는 Cloud/DC 가 다르고 바뀌므로 거기에 기대지 않는다.
+md.renderer.rules.heading_open = (tokens, idx, opts, _env, self) => {
+    const slug = ctx.bodySlugs[ctx.headingSeq++];
+    const open = self.renderToken(tokens, idx, opts);
+    if (!slug || !ctx.anchorNames.has(slug))
+        return open;
+    ctx.anchorsPlaced++;
+    return anchorMacro(slug) + open;
+};
 md.renderer.rules.fence = (tokens, idx) => {
     const t = tokens[idx];
     const lang = (t.info || '').trim().split(/\s+/)[0];
@@ -44,12 +83,19 @@ md.renderer.rules.fence = (tokens, idx) => {
 };
 md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
     const href = tokens[idx].attrGet('href') || '';
-    const targetTitle = resolveInternalLink(href);
-    if (targetTitle) {
+    const t = resolveInternalLink(href);
+    // 페이지도 앵커도 못 정하면 Confluence 링크로 만들 게 없다 → 원문 <a> 유지
+    if (t && (t.title || t.anchor)) {
         ctx.linkStack.push(true);
         ctx.internalLinks++;
-        ctx.linkedTitles.add(targetTitle);
-        return `<ac:link><ri:page ri:content-title="${escapeXml(targetTitle)}" /><ac:link-body>`;
+        if (t.title)
+            ctx.linkedTitles.add(t.title);
+        if (t.anchor)
+            ctx.anchorLinks++;
+        // 앵커 이름은 헤딩 텍스트 그대로다. ri:page 가 없으면 같은 페이지 안의 이동이 된다.
+        const anchor = t.anchor ? ` ac:anchor="${escapeXml(t.anchor)}"` : '';
+        const page = t.title ? `<ri:page ri:content-title="${escapeXml(t.title)}" />` : '';
+        return `<ac:link${anchor}>${page}<ac:link-body>`;
     }
     ctx.linkStack.push(false);
     return self.renderToken(tokens, idx, opts);
@@ -86,14 +132,30 @@ export function splitTitleAndBody(markdown, fallback) {
 }
 /**
  * 본문 markdown 을 storage format 으로 변환(base 기준 상대경로로 링크·이미지 해석).
- * resolveLink 를 주면 Obsidian 의 [[wikilink]]·![[embed]] 를 먼저 표준 링크로 정규화한다.
  */
-export function toStorage(markdown, rel, titleIndex, base, resolveLink) {
+export function toStorage(markdown, rel, titleIndex, base, opts = {}) {
     baseDir = base;
-    ctx = { fileDir: dirname(rel) === '.' ? '' : dirname(rel), titleIndex, images: [], internalLinks: 0, linkStack: [], linkedTitles: new Set() };
-    const src = resolveLink ? resolveWikilinks(markdown, resolveLink) : markdown;
+    ctx = {
+        ...emptyCtx(),
+        fileDir: dirname(rel) === '.' ? '' : dirname(rel),
+        titleIndex,
+        anchorIndex: opts.anchorIndex ?? {},
+        selfRel: rel,
+        selfTitle: opts.title ?? '',
+        anchorNames: opts.anchorNames ?? new Set(),
+        bodySlugs: opts.bodySlugs ?? [],
+    };
+    const src = opts.resolveLink ? resolveWikilinks(markdown, opts.resolveLink) : markdown;
     const storage = md.render(src);
-    return { storage, images: ctx.images, internalLinks: ctx.internalLinks, linkedTitles: [...ctx.linkedTitles] };
+    return {
+        storage,
+        images: ctx.images,
+        internalLinks: ctx.internalLinks,
+        anchorLinks: ctx.anchorLinks,
+        anchorsPlaced: ctx.anchorsPlaced,
+        deadAnchors: ctx.deadAnchors,
+        linkedTitles: [...ctx.linkedTitles],
+    };
 }
 /**
  * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 이미지의 내용 해시.

package/dist/obsidian.js

@@ -9,6 +9,7 @@
  * frontmatter 는 평면 `key: value` 만 다룬다. 중첩·리스트가 필요할 만큼 복잡한 메타데이터는
  * 이 도구의 관심사가 아니며, 알 수 없는 키는 건드리지 않고 보존한다.
  */
+import { wikilinkAnchorToSlug } from './anchors.js';
 const FENCE = /^\s*(?:```|~~~)/;
 // [[대상]] · [[대상|별칭]] · [[대상#헤딩]] · ![[임베드]]
 const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
@@ -74,7 +75,12 @@ export function resolveWikilinks(md, resolve) {
         if (!found)
             return whole; // 해석 실패 → 원문 보존
         const label = (alias ?? target).trim();
-        return embed ? `![${label}](${dest(found)})` : `[${label}](${dest(found + (hash ?? ''))})`;
+        if (embed)
+            return `![${label}](${dest(found)})`;
+        // Obsidian 은 섹션을 헤딩 텍스트로 가리키지만(`#1. 신뢰 — Trust Registry`)
+        // 표준 마크다운은 슬러그를 쓴다. 블록 참조(`#^id`)는 대응물이 없어 링크만 남긴다.
+        const slug = hash ? wikilinkAnchorToSlug(hash.slice(1)) : null;
+        return `[${label}](${dest(found + (slug ? `#${slug}` : ''))})`;
     }));
 }
 // [text](dest) — dest 는 <...> 로 감싸였을 수 있다. 앞의 ! 는 이미지 임베드.

package/dist/pull.js

@@ -12,12 +12,17 @@ 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 } from './obsidian.js';
+import { buildFrontmatter, splitFrontmatter } from './obsidian.js';
+import { collectHeadings, matchConfluenceAnchor } from './anchors.js';
 import { cyan, dim, green, red, yellow } from './colors.js';
 // 첨부 이미지는 항상 <md위치>/attachments/<문서명>/ 하위에 저장한다.
 const ASSETS_DIR = 'attachments';
 /** 마크다운 링크 중 Confluence 페이지를 가리키는 것: [text](https://.../pages/<id>/...) */
 const PAGE_LINK = /\[([^\]]*)\]\(<?(https?:\/\/[^\s)<>]*?\/pages\/(\d+)[^\s)<>]*?)>?\)/g;
+/** 같은 문서 안의 앵커: [text](#앵커) */
+const SELF_ANCHOR = /\[([^\]]*)\]\(#([^)\s]+)\)/g;
+/** 다른 페이지의 섹션: [text](https://.../pages/<id>/제목#앵커) — 앵커만 따로 잡는다 */
+const PAGE_ANCHOR = /(\[[^\]]*\]\(<?https?:\/\/[^\s)<>]*?\/pages\/(\d+)[^\s)<>#]*)#([^\s)<>]+?)(>?\))/g;
 function optVal(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
@@ -128,12 +133,66 @@ async function pullNode(ctx, id, destDir) {
         return { pages: 0, folders: 0 };
     }
 }
+function readDocInfo(file) {
+    const { data, body } = splitFrontmatter(readFileSync(file, 'utf8'));
+    const headings = collectHeadings(body);
+    return {
+        title: data.title ?? '',
+        headings,
+        textBySlug: new Map(headings.map((h) => [h.slug, h.text])),
+    };
+}
+/**
+ * Confluence 가 만든 헤딩 앵커를 마크다운 슬러그로 바꾼다.
+ *
+ * Confluence 의 앵커 id 는 `<페이지제목><헤딩텍스트>`(공백 제거) 라서 Obsidian·GitHub 에서는
+ * 아무 데도 가리키지 못한다. 실제 헤딩을 찾아 그 문서의 슬러그로 바꿔 줘야 링크가 산다.
+ * relinkPass 보다 **먼저** 돈다 — 아직 링크가 절대 URL 이라 어느 페이지인지 id 로 알 수 있기 때문이다.
+ */
+export function anchorPass(written, pathById) {
+    const info = new Map();
+    for (const f of written)
+        info.set(f, readDocInfo(f));
+    let count = 0;
+    for (const file of written) {
+        const self = info.get(file);
+        const before = readFileSync(file, 'utf8');
+        // 우리가 올린 페이지는 Anchor 매크로 이름이 이미 마크다운 슬러그라 그대로 두면 된다.
+        // Confluence 에서 직접 쓴 페이지만 헤딩을 찾아 맞춘다.
+        const toSlug = (frag, d) => {
+            if (d.textBySlug.has(frag))
+                return null; // 이미 올바른 슬러그
+            return matchConfluenceAnchor(frag, d.headings, d.title)?.slug ?? null;
+        };
+        let after = before.replace(SELF_ANCHOR, (whole, label, frag) => {
+            const slug = toSlug(frag, self);
+            if (!slug)
+                return whole; // 이미 맞거나 못 찾음 → 손대지 않는다(엉뚱한 곳으로 보내지 않기 위해)
+            count++;
+            return `[${label}](#${slug})`;
+        });
+        after = after.replace(PAGE_ANCHOR, (whole, head, id, frag, tail) => {
+            const target = pathById.get(id);
+            const ti = target && info.get(target);
+            if (!ti)
+                return whole; // 이번에 안 받은 페이지 → 원본 URL 이 살아 있어야 한다
+            const slug = toSlug(frag, ti);
+            if (!slug)
+                return whole;
+            count++;
+            return `${head}#${slug}${tail}`;
+        });
+        if (after !== before)
+            writeFileSync(file, after);
+    }
+    return { count, info };
+}
 /**
  * 함께 받은 페이지를 가리키는 절대 Confluence URL 을 상대 .md 링크(또는 [[wikilink]])로 바꾼다.
  * 이번에 받지 않은 페이지의 링크는 절대 URL 그대로 둔다(깨진 링크를 만들지 않는다).
  * 반환값은 재작성한 링크 수.
  */
-export function relinkPass(written, pathById, wikilinks) {
+export function relinkPass(written, pathById, wikilinks, info) {
     const noExt = (p) => basename(p).replace(/\.md$/i, '');
     // wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 유일할 때만 안전하게 쓸 수 있다.
     const nameCount = new Map();
@@ -149,12 +208,16 @@ export function relinkPass(written, pathById, wikilinks) {
             count++;
             const name = noExt(target);
             const label = (text || name).trim();
+            const slug = url.includes('#') ? url.split('#').slice(1).join('#') : '';
             if (wikilinks && nameCount.get(name) === 1) {
-                return label === name ? `[[${name}]]` : `[[${name}|${label}]]`;
+                // Obsidian 은 슬러그가 아니라 헤딩 텍스트로 섹션을 가리킨다: [[문서#헤딩 텍스트]]
+                const heading = slug ? info?.get(target)?.textBySlug.get(slug) : undefined;
+                if (!heading)
+                    return label === name ? `[[${name}]]` : `[[${name}|${label}]]`;
+                return `[[${name}#${heading}|${label}]]`;
             }
-            const anchor = url.includes('#') ? '#' + url.split('#').slice(1).join('#') : '';
             const rel = relative(dirname(file), target).split('\\').join('/');
-            return `[${label}](${dest(rel + anchor)})`;
+            return `[${label}](${dest(rel + (slug ? `#${slug}` : ''))})`;
         });
         if (after !== before)
             writeFileSync(file, after);
@@ -177,9 +240,12 @@ export async function runPull(argv) {
         pathById: new Map(),
     };
     const done = (c) => {
-        const relinked = relinkPass(ctx.written, ctx.pathById, ctx.obsidian);
+        // 앵커를 먼저 슬러그로 바꾼 뒤 링크를 상대경로로 옮긴다(순서가 바뀌면 어느 페이지의 헤딩인지 알 수 없다).
+        const { count: anchors, info } = anchorPass(ctx.written, ctx.pathById);
+        const relinked = relinkPass(ctx.written, ctx.pathById, ctx.obsidian, info);
         console.log(`\n${green('완료')}  페이지 ${c.pages}개${c.folders ? `, 폴더 ${c.folders}개` : ''} 생성` +
-            (relinked ? `  ${cyan(`내부링크 ${relinked}개 연결`)}` : ''));
+            (relinked ? `  ${cyan(`내부링크 ${relinked}개 연결`)}` : '') +
+            (anchors ? `  ${cyan(`섹션링크 ${anchors}개 복원`)}` : ''));
     };
     // --space: 스페이스 홈페이지(콘텐츠 트리 루트)부터 전체를 재귀적으로 가져옴
     if (wholeSpace) {

package/dist/sync.js

@@ -18,7 +18,7 @@ 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, buildTitleIndex, buildFolderIndex, buildVault, vaultResolver, readDoc, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
+import { collectMarkdown, collectAssets, buildDocIndex, resolveAnchorTargets, buildFolderIndex, buildVault, vaultResolver, 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';
@@ -108,10 +108,20 @@ async function main() {
     const allRel = collected.filter((r) => !ignorer.ignores(r)); // 제외된 문서는 모든 단계에서 빠짐
     const ignoredCount = collected.length - allRel.length;
     const folderIndex = buildFolderIndex(allRel);
-    const titleIndex = buildTitleIndex(allRel, BASE_DIR); // 링크 변환은 항상 전체 기준
+    // 링크·섹션 링크 변환은 항상 전체 기준(선택 동기화여도 대상 문서의 제목·헤딩을 알아야 한다)
+    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)));
-    const render = (rel, body) => toStorage(body, rel, titleIndex, BASE_DIR, vaultResolver(rel, vault));
+    // 누가 어느 헤딩을 가리키는지 먼저 모은다 — 그 헤딩에만 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 selected = positionals.length
         ? withParents(resolveSelection(allRel, positionals, BASE_DIR), folderIndex)
         : allRel;
@@ -158,7 +168,7 @@ async function main() {
                     console.log(`  [${fex?.pageId ? gray('폴더') : green('폴더+')}] 📁 ${d}/`);
                 }
             const { title, body, fm } = readDoc(BASE_DIR, rel);
-            const r = render(rel, body);
+            const r = render(rel, body, title);
             const hash = docHash(title, r);
             const ex = mapping[rel];
             // 매핑엔 없지만 frontmatter 에 pageId 가 있으면 신규 생성이 아니라 기존 페이지에 연결된다
@@ -166,7 +176,12 @@ async function main() {
                 ? (fm.pageId ? cyan('연결') : green('신규'))
                 : ex.hash === hash ? gray('동일') : yellow('변경');
             const pk = parentKeyOf(rel, folderIndex);
-            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}, 이미지: ${r.images.length})`)}`);
+            const anchorNote = r.anchorLinks || r.anchorsPlaced
+                ? `, 섹션링크: ${r.anchorLinks}, 앵커: ${r.anchorsPlaced}` : '';
+            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}${anchorNote}, 이미지: ${r.images.length})`)}`);
+            if (r.deadAnchors.length) {
+                console.error(yellow(`    ⚠ 대응 헤딩 없는 앵커 ${r.deadAnchors.length}개: `) + dim(r.deadAnchors.slice(0, 3).join(' ')));
+            }
         }
         console.log('\n' + dim('--dry-run: 실제 호출 없음.'));
         return;
@@ -229,9 +244,12 @@ async function main() {
             continue;
         }
         const { title, body, fm } = readDoc(BASE_DIR, rel);
-        const r = render(rel, body);
+        const r = render(rel, body, title);
         const hash = docHash(title, r);
         const pk = parentKeyOf(rel, folderIndex);
+        if (r.deadAnchors.length) {
+            console.error(yellow(`  ⚠ 대응 헤딩 없는 앵커  ${rel}`) + dim(`  ${r.deadAnchors.slice(0, 3).join(' ')}${r.deadAnchors.length > 3 ? ` 외 ${r.deadAnchors.length - 3}` : ''}`));
+        }
         const parentId = pk ? work[pk]?.pageId : env.parentId;
         rendered.set(rel, { ...r, title, hash, parentId });
         if (pk && !parentId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Confluence Cloud ↔ Markdown 양방향 동기화 CLI — 마크다운을 Confluence 페이지로 발행(push)하고, Confluence 페이지·폴더·스페이스를 마크다운으로 가져옵니다(pull).",
   "keywords": [