@wonseok-han/confluence-sync 1.0.0 → 1.2.0

package/dist/docs.js

@@ -3,28 +3,153 @@
  * 폴더의 README.md 가 대표 페이지가 되고 같은 폴더의 다른 문서는 그 자식이 된다.
  */
 import { readdirSync, readFileSync } from 'node:fs';
-import { join, resolve, relative } from 'node:path';
+import { join, resolve, relative, basename, dirname } from 'node:path';
 import { splitTitleAndBody } from './markdown.js';
-/** dir 이하의 모든 .md 절대경로를 재귀 수집 */
-export function collectMarkdown(dir) {
+import { splitFrontmatter } from './obsidian.js';
+import { buildAnchorIndex, collectHeadings, collectLinkAnchors, wikilinkAnchorToSlug, decodeAnchor, } from './anchors.js';
+/**
+ * 숨김 디렉토리는 문서가 아니다. Obsidian vault 의 `.obsidian/`(설정)·`.trash/`(휴지통) 과
+ * `.git/`·`node_modules/` 가 여기서 걸러진다.
+ */
+const skipDir = (name) => name.startsWith('.') || name === 'node_modules';
+/** dir 이하의 파일 절대경로를 재귀 수집(pick 이 true 인 것만). */
+function walk(dir, pick) {
     const out = [];
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const full = join(dir, entry.name);
-        if (entry.isDirectory())
-            out.push(...collectMarkdown(full));
-        else if (entry.isFile() && entry.name.endsWith('.md'))
+        if (entry.isDirectory()) {
+            if (!skipDir(entry.name))
+                out.push(...walk(full, pick));
+        }
+        else if (entry.isFile() && pick(entry.name)) {
             out.push(full);
+        }
     }
     return out;
 }
-/** base 상대 경로 → 문서 제목(첫 H1) 인덱스 */
-export function buildTitleIndex(rels, baseDir) {
-    const idx = {};
+const isMd = (name) => name.toLowerCase().endsWith('.md');
+/** dir 이하의 모든 .md 절대경로를 재귀 수집 */
+export function collectMarkdown(dir) {
+    return walk(dir, isMd);
+}
+/** dir 이하의 .md 가 아닌 파일(이미지 등 첨부 후보) 절대경로를 재귀 수집 */
+export function collectAssets(dir) {
+    return walk(dir, (n) => !isMd(n));
+}
+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, ''));
+    // 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 buildDocIndex(rels, baseDir) {
+    const titles = {};
+    const anchors = {};
+    const docs = {};
     for (const rel of rels) {
-        const { title } = splitTitleAndBody(readFileSync(resolve(baseDir, rel), 'utf8'), rel);
-        idx[rel] = title;
+        const doc = readDoc(baseDir, rel);
+        titles[rel] = doc.title;
+        anchors[rel] = doc.anchors;
+        docs[rel] = doc;
     }
-    return idx;
+    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 상대 경로 인덱스.
+ * Obsidian 은 `[[파일명]]`(짧은 이름)과 `[[폴더/파일명]]`(경로) 을 모두 허용하므로 둘 다 등록한다.
+ * 짧은 이름이 겹치면 경로가 사전순으로 앞서는 쪽이 이긴다(Obsidian 의 "가장 가까운 것" 규칙과는 다르지만 결정적이다).
+ */
+export function buildVault(mdRels, assetRels) {
+    const index = (rels, stripExt) => {
+        const idx = {};
+        for (const rel of [...rels].sort()) {
+            const withoutExt = stripExt ? rel.replace(/\.md$/i, '') : rel;
+            for (const key of [withoutExt, basename(withoutExt)]) {
+                const k = key.toLowerCase();
+                if (!(k in idx))
+                    idx[k] = rel; // 먼저 등록된(사전순 앞선) 것이 이긴다
+            }
+        }
+        return idx;
+    };
+    return { notes: index(mdRels, true), assets: index(assetRels, false) };
+}
+/** 파일(rel) 기준으로 wikilink 대상을 상대경로로 풀어주는 resolver. */
+export function vaultResolver(rel, vault) {
+    const dir = dirname(rel) === '.' ? '' : dirname(rel);
+    return (target, embed) => {
+        const key = target.toLowerCase().replace(/\.md$/i, '');
+        // 임베드(![[...]])는 대개 이미지, 링크([[...]])는 대개 노트 → 각자 먼저 찾아본다
+        const hit = embed
+            ? (vault.assets[target.toLowerCase()] ?? vault.notes[key])
+            : (vault.notes[key] ?? vault.assets[target.toLowerCase()]);
+        if (!hit)
+            return null;
+        const r = relative(dir || '.', hit).split('\\').join('/');
+        return r || null;
+    };
 }
 const isReadme = (base) => /README\.md$/.test(base);
 /** 폴더 경로 → 그 폴더의 대표 README(base 상대) 인덱스 */

package/dist/help.js

@@ -16,12 +16,14 @@ export function printHelp() {
     const h = (s) => bold(s); // 섹션 제목
     const o = (s) => cyan(s); // 옵션/명령
     console.log(`${bold(cyan(`confluence-sync v${readPkgVersion()}`))}
-${dim('Markdown 디렉토리를 Confluence Cloud 페이지로 단방향 동기화합니다.')}
+${dim('Confluence Cloud ↔ Markdown 양방향 동기화 CLI.')}
+${dim('짧은 이름')} ${o('csync')} ${dim('로도 실행할 수 있습니다(아래 confluence-sync 를 csync 로 대체 가능).')}
 
 ${h('사용법:')}
   ${o('confluence-sync')} [옵션] [경로...]      문서를 동기화(md → Confluence)
   ${o('confluence-sync init')}                  대화형으로 .env 설정 파일 생성
   ${o('confluence-sync pull <pageId|url>')}     Confluence 페이지/폴더를 .md 로 가져오기(역방향)
+  ${o('confluence-sync convert --to <형식>')}   이미 받은 .md 의 링크 표기를 바꾸기(로컬 전용)
   ${o('confluence-sync --help | --version')}
 
 ${h('동기화 옵션:')}
@@ -42,13 +44,45 @@ ${h('경로 인자:')}
   예)  ${o('confluence-sync 20-design')}        ${o('confluence-sync 90-glossary.md')}
 
 ${h('pull(역방향) 옵션:')}
-  ${o('--out <dir>')}       .md 를 생성할 디렉토리(기본: 현재 폴더)
-  ${o('--children')}        하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
-  ${o('--space')}          대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
+  ${o('--out <dir>')}         .md 를 생성할 디렉토리(기본: 현재 폴더)
+  ${o('--children')}          하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
+  ${o('--space')}             대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
+  ${o('--obsidian')}       내부 링크를 [[wikilink]] 로 출력(기본: 어디서나 열리는 상대 .md 링크)
   (이미지는 항상 attachments/<문서명>/ 하위에 저장됨)
   예)  ${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 링크 (되돌리기)
+  ${o('--fix')}            옛 pull 결과 보정 — 코드블록 언어(java→plaintext)·CSS 잔해·
+                   불필요한 \\ 이스케이프·리스트 사이 빈 줄
+  ${o('--base <dir>')}     링크를 해석할 문서 트리 루트(기본: 준 경로들의 공통 상위 폴더)
+  ${o('--out <dir>')}      원본을 두고 결과를 다른 트리에 쓰기(참조된 첨부도 함께 복사)
+  ${o('--dry-run')}        바뀔 파일만 출력하고 쓰지 않음
+
+  파일·폴더를 여러 개 줄 수 있고, 안 주면 base 전체가 대상입니다.
+  ${o('--out')} 없이 실행하면 ${dim('원본 파일을 덮어씁니다')}.
+  예)  ${o('confluence-sync convert --fix ./docs --dry-run')}
+       ${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]]')} · ${o('[[문서#헤딩]]')} · YAML frontmatter
+  (frontmatter 의 ${o('title')} 이 페이지 제목이 되고, ${o('pageId')} 가 있으면 매핑이 없어도 그 페이지를 갱신합니다).
+
 ${h('설정(.env):')}
   실행 위치(cwd)의 .env 또는 셸 환경변수를 읽습니다.
   필수: CONFLUENCE_BASE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY

package/dist/html2md.js

@@ -22,7 +22,7 @@ const linkDest = (p) => (/\s/.test(p) ? `<${p}>` : p);
  * (예: `**7️⃣**\-**1️⃣**` — 두 굵은 글씨 사이 텍스트 노드가 "-" 하나라 노드 시작으로 취급)
  * 줄 맨 앞의 진짜 마커 이스케이프는 보존하고, 그 뒤(줄 중간)의 것만 되돌린다. 코드블록은 건드리지 않는다.
  */
-function relaxEscapes(md) {
+export function relaxEscapes(md) {
     let inFence = false;
     return md
         .split('\n')
@@ -39,6 +39,8 @@ function relaxEscapes(md) {
             .slice(head.length)
             // 줄 중간의 - + . > 는 마커가 아니므로 이스케이프 불필요
             .replace(/\\([-+.>])/g, '$1')
+            // 단어 내부 밑줄은 CommonMark 에서 강조가 아니다 (:11_eleven_square_blue: 같은 이모지 코드)
+            .replace(/(\w)\\_(?=\w)/g, '$1_')
             // 링크가 아닌 대괄호 쌍(뒤에 ( 나 [ 가 오지 않음)은 이스케이프 불필요
             .replace(/\\\[([^[\]\n]*)\\\](?!\s*[([])/g, '[$1]');
         return head + rest;

package/dist/markdown.js

@@ -9,6 +9,8 @@ import { readFileSync, existsSync } from 'node:fs';
 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 이 퍼센트 인코딩한 링크/이미지 경로를 실제 경로로 디코드(실패 시 원본). */
@@ -21,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];
@@ -43,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);
@@ -83,12 +130,32 @@ export function splitTitleAndBody(markdown, fallback) {
     lines.splice(i, 1);
     return { title, body: lines.join('\n') };
 }
-/** 본문 markdown 을 storage format 으로 변환(base 기준 상대경로로 링크·이미지 해석). */
-export function toStorage(markdown, rel, titleIndex, base) {
+/**
+ * 본문 markdown 을 storage format 으로 변환(base 기준 상대경로로 링크·이미지 해석).
+ */
+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 storage = md.render(markdown);
-    return { storage, images: ctx.images, internalLinks: ctx.internalLinks, linkedTitles: [...ctx.linkedTitles] };
+    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,
+        anchorLinks: ctx.anchorLinks,
+        anchorsPlaced: ctx.anchorsPlaced,
+        deadAnchors: ctx.deadAnchors,
+        linkedTitles: [...ctx.linkedTitles],
+    };
 }
 /**
  * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 이미지의 내용 해시.

package/dist/obsidian.js

@@ -0,0 +1,100 @@
+/**
+ * Obsidian 브릿지 — vault 관례와 이 도구의 표준 마크다운 사이를 잇는다.
+ *
+ * 원칙: **표준을 내보내고, 방언을 받아들인다.**
+ *  - push: vault 에서 쓴 YAML frontmatter · [[wikilink]] · ![[embed]] 를 이해해 그대로 발행한다.
+ *  - pull: Obsidian·GitHub·VS Code 어디서나 열리는 표준 상대 링크로 내보낸다
+ *          (frontmatter 의 pageId 가 왕복 동기화의 앵커가 된다).
+ *
+ * frontmatter 는 평면 `key: value` 만 다룬다. 중첩·리스트가 필요할 만큼 복잡한 메타데이터는
+ * 이 도구의 관심사가 아니며, 알 수 없는 키는 건드리지 않고 보존한다.
+ */
+import { wikilinkAnchorToSlug } from './anchors.js';
+const FENCE = /^\s*(?:```|~~~)/;
+// [[대상]] · [[대상|별칭]] · [[대상#헤딩]] · ![[임베드]]
+const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
+/**
+ * 문서 맨 앞의 YAML frontmatter 를 분리한다. 없으면 data 는 빈 객체.
+ * `key: value` 한 줄짜리만 인식하고, 값의 감싼 따옴표는 벗긴다.
+ */
+export function splitFrontmatter(raw) {
+    const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+    if (!m)
+        return { data: {}, body: raw };
+    const data = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+        if (!kv)
+            continue; // 중첩/리스트 등 평면이 아닌 줄은 무시(보존은 하지 않음)
+        data[kv[1]] = kv[2].trim().replace(/^["'](.*)["']$/, '$1');
+    }
+    return { data, body: raw.slice(m[0].length) };
+}
+/** 평면 frontmatter 블록 생성. 값이 비면 그 키는 생략한다. */
+export function buildFrontmatter(data) {
+    const lines = Object.entries(data)
+        .filter(([, v]) => v !== undefined && v !== null && v !== '')
+        // 콜론·따옴표·선행 특수문자가 있으면 YAML 이 깨지므로 인용한다
+        .map(([k, v]) => `${k}: ${/[:#"'\n]|^\s|\s$/.test(v) ? JSON.stringify(v) : v}`);
+    return lines.length ? `---\n${lines.join('\n')}\n---\n\n` : '';
+}
+/** 공백이 있으면 <...> 로 감싼다(markdown-it 이 목적지를 통째로 파싱하도록). */
+const dest = (p) => (/\s/.test(p) ? `<${p}>` : p);
+/**
+ * 마크다운 본문에서 "산문" 부분에만 변환을 적용한다.
+ * 코드블록(``` / ~~~)과 인라인 코드(`...`) 안은 그대로 둔다 — 링크처럼 생긴 예제 코드를
+ * 망가뜨리지 않기 위해서다.
+ */
+function mapProse(md, fn) {
+    let inFence = false;
+    return md
+        .split('\n')
+        .map((line) => {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            return line;
+        }
+        if (inFence)
+            return line;
+        // 홀수 인덱스 = 인라인 코드 스팬 → 원문 유지
+        return line
+            .split(/(`+[^`]*`+)/)
+            .map((seg, i) => (i % 2 ? seg : fn(seg)))
+            .join('');
+    })
+        .join('\n');
+}
+/**
+ * [[wikilink]] · ![[embed]] → 표준 마크다운 링크.
+ * 해석에 실패한 링크는 원문 그대로 남겨 (조용히 사라지지 않고) 눈에 띄게 한다.
+ */
+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);
+        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;
+        return `[${label}](${dest(found + (slug ? `#${slug}` : ''))})`;
+    }));
+}
+// [text](dest) — dest 는 <...> 로 감싸였을 수 있다. 앞의 ! 는 이미지 임베드.
+const MD_LINK = /(!?)\[([^\]]*)\]\((<[^>]+>|[^()\s]+)\)/g;
+/**
+ * 표준 마크다운 링크 → [[wikilink]] (resolveWikilinks 의 역변환).
+ * toWikilink 가 null 을 주면(= 외부 URL·이미지·대상 불명) 그 링크는 그대로 둔다.
+ * 이미지 임베드(`![...]()`)는 건드리지 않는다 — 표준 문법이 Obsidian 에서도 그대로 렌더된다.
+ */
+export function linksToWikilinks(md, toWikilink) {
+    return mapProse(md, (s) => s.replace(MD_LINK, (whole, bang, label, rawDest) => {
+        if (bang === '!')
+            return whole; // 이미지는 표준 링크 유지
+        const d = rawDest.replace(/^<(.*)>$/, '$1');
+        return toWikilink(d, label) ?? whole;
+    }));
+}