confluence-md-sync 0.4.0 → 0.5.0

package/README.md

@@ -180,19 +180,29 @@ Attachments and page links become `{{img:...}}` / `{{file:...}}` /
 | Mode | For | What it does |
 | --- | --- | --- |
 | `faithful` *(default)* | round-trip, editing then re-publishing | **Loss-free by construction.** Clean Markdown → macro markers → verbatim storage (raw HTML, or a ` ```confluence-storage ` fence) as a fallback. Perfect fidelity, but the raw-HTML blocks (complex tables, wrappers) render poorly in some Markdown viewers. |
-| `readable` | reading, diffing, docs you won't publish back | **Clean Markdown, no raw HTML.** Complex tables are flattened to GFM (merged cells → filled grid, block cells → `• …` joined by `<br>`), styled spans/wrappers are unwrapped, entities decoded. Keeps the content; **drops** colours, exact merge geometry, wrappers — *not* round-trippable. |
+| `readable` | reading, diffing, docs you won't publish back | **Clean Markdown, no raw HTML.** Complex tables are flattened to GFM (merged cells → filled grid, block cells → `• …` joined by `<br>`), styled spans/wrappers are unwrapped, entities decoded, and `<br>` in paragraphs becomes a real line break (inside table cells it stays `<br>` — GFM cells can't hold newlines). Keeps the content; **drops** colours, exact merge geometry, wrappers — *not* round-trippable. |
+
+Images and attachments are downloaded by default (pass
+`downloadAttachments: false` to skip). They land in `attachments/` next to
+the Markdown, and the page body references them via `{{img:name}}` /
+`{{file:name}}` — in both modes.
 
 ```ts
 import { exportPage } from 'confluence-md-sync';
 
 const { markdownPath, images, downloaded } = await exportPage(
   '123456789',
-  { outDir: 'exported' },              // faithful; writes page.md + attachments/
+  { outDir: 'exported' },              // faithful; exported/page.md + exported/attachments/
   cfg,
 );
+console.log(downloaded);               // Map<filename, localPath> of saved attachments
 
-// Readable variant for humans:
+// Readable variant for humans (writes page.md + ./attachments/ next to it):
 await exportPage('123456789', { outFile: 'page.md', mode: 'readable' }, cfg);
+
+// Self-contained (local <img>/links) with wide tables unfolded to records:
+await exportPage('123456789',
+  { outDir: 'doc', attachments: 'local', tables: 'records' }, cfg);
 ```
 
 Round-trip means *edit the Markdown, then publish it straight back*:
@@ -222,12 +232,28 @@ schema-version, attribute/parameter order and entity vs literal forms are
 normalised away (Confluence itself rewrites these on every save). Use
 `compareStorage(a, b)` directly to diff two storage fragments.
 
-From the CLI:
+### Which export variant?
+
+Attachments download to `attachments/` next to the `.md` in every variant
+(pass `--no-attachments` to skip). Flags compose; `--local` and `--records`
+imply `--readable`.
+
+| Command | Use it when | Output |
+| --- | --- | --- |
+| `export <id> --out page.md` | you'll **edit and publish it back** | Faithful, round-trippable; raw HTML kept for what Markdown can't express. |
+| `export <id> --out page.md --readable` | **reading / diffing** in a Markdown viewer | Clean Markdown, no raw HTML; complex tables → GFM. Not round-trippable. |
+| `export <id> --out-dir doc --local` | a **self-contained folder to view offline** | Like `--readable`, but images become `<img src="attachments/…">` (sizes kept) and files become `[name](attachments/…)` links pointing at the downloaded files. |
+| `export <id> --out page.md --records` | tables are **too wide** to read as a grid | Every table row is unfolded into a `**Header:** value` record (records split by `---`). Best for tables that have a header row. |
+| `export <id> --out-dir doc --local --records` | an **offline, wide-table-friendly** read | Both of the above together. |
+| `roundtrip <id>` | **checking** a page converts with no loss (CI) | Writes nothing; exits `2` if faithful conversion would lose markup. |
 
 ```bash
-confluence-md-sync export    123456789 --out page.md              # faithful
-confluence-md-sync export    123456789 --out page.md --readable   # clean Markdown
-confluence-md-sync roundtrip 123456789 --show-markdown            # exit 2 on loss
+confluence-md-sync export    123456789 --out page.md                     # faithful (edit → publish back)
+confluence-md-sync export    123456789 --out page.md --readable          # clean Markdown to read
+confluence-md-sync export    123456789 --out-dir doc --local             # self-contained: page.md + attachments/
+confluence-md-sync export    123456789 --out page.md --records           # wide tables → records
+confluence-md-sync export    123456789 --out-dir doc --local --records   # offline + records
+confluence-md-sync roundtrip 123456789 --show-markdown                   # verify, exit 2 on loss
 ```
 
 ## Read pages and tables

package/dist/cli.js

@@ -21,7 +21,7 @@ const HELP = `confluence-md-sync — Markdown ⇄ Confluence
 
 Usage:
   confluence-md-sync publish   <markdown-file> [options]
-  confluence-md-sync export    <page-id> [--out <file> | --out-dir <dir>] [--readable] [--no-attachments]
+  confluence-md-sync export    <page-id> [--out <file> | --out-dir <dir>] [--readable] [--local] [--records] [--no-attachments]
   confluence-md-sync roundtrip <page-id> [--show-markdown]
 
 publish options:
@@ -46,6 +46,12 @@ export options:
   --readable            Prefer clean Markdown over fidelity: no raw HTML blocks,
                         complex tables flattened to GFM. Not round-trippable —
                         loses styling/exact cell merges, keeps the content
+  --local               Reference downloaded attachments as local files:
+                        images as HTML <img src="attachments/…">, other files
+                        as [name](attachments/…) links. Implies --readable
+  --records             Unfold every table row into a "**Header:** value"
+                        record (records split by ---). For wide tables that
+                        don't fit as GFM. Implies --readable
   --no-attachments      Do not download referenced attachments
 
 roundtrip options:
@@ -74,6 +80,8 @@ async function main() {
             out: { type: 'string' },
             'out-dir': { type: 'string' },
             readable: { type: 'boolean' },
+            local: { type: 'boolean' },
+            records: { type: 'boolean' },
             'no-attachments': { type: 'boolean' },
             'show-markdown': { type: 'boolean' },
             help: { type: 'boolean' },
@@ -107,13 +115,17 @@ async function main() {
     if (command === 'export') {
         if (!arg)
             throw new Error('export: page id is required');
+        // --local и --records подразумевают readable-обработку текста.
+        const readable = values.readable || values.local || values.records;
         const result = await exportPage(arg, {
             outFile: values.out,
             outDir: values['out-dir'],
             downloadAttachments: !values['no-attachments'],
-            mode: values.readable ? 'readable' : 'faithful',
+            mode: readable ? 'readable' : 'faithful',
+            attachments: values.local ? 'local' : 'placeholder',
+            tables: values.records ? 'records' : 'auto',
         }, cfg);
-        const tail = values.readable
+        const tail = readable
             ? `${result.stats.lossy} block(s) simplified`
             : `${result.stats.fenced} raw storage block(s)`;
         console.log(`[cli] exported page ${result.pageId} "${result.title}" v${result.version} → ${result.markdownPath}` +

package/dist/export/export-page.d.ts

@@ -23,6 +23,13 @@ export interface ExportPageOptions {
      * 'readable' — чистый Markdown ценой оформления (round-trip не гарантирован).
      */
     mode?: 'faithful' | 'readable';
+    /**
+     * 'placeholder' (default) — {{img:}}/{{file:}}; 'local' — картинки как
+     * HTML `<img src="attachments/…">`, файлы как md-ссылки. Подразумевает readable.
+     */
+    attachments?: 'placeholder' | 'local';
+    /** 'auto' (default) или 'records' — строки таблиц как записи. Подразумевает readable. */
+    tables?: 'auto' | 'records';
     registry?: MacroRegistry;
 }
 export interface ExportPageResult extends StorageToMarkdownResult {

package/dist/export/export-page.js

@@ -9,7 +9,12 @@ import { storageToMarkdown } from './to-markdown.js';
 export async function exportPage(pageId, opts, cfg) {
     const client = new ConfluenceClient(cfg);
     const page = await client.getPageStorage(pageId);
-    const converted = storageToMarkdown(page.storage, { registry: opts.registry, mode: opts.mode });
+    const converted = storageToMarkdown(page.storage, {
+        registry: opts.registry,
+        mode: opts.mode,
+        attachments: opts.attachments,
+        tables: opts.tables,
+    });
     const markdownPath = opts.outFile ?? join(opts.outDir ?? `./${pageId}`, 'page.md');
     mkdirSync(dirname(markdownPath), { recursive: true });
     writeFileSync(markdownPath, converted.markdown);

package/dist/export/to-markdown.d.ts

@@ -28,6 +28,24 @@ export interface StorageToMarkdownOptions {
      * 'readable' — чистый Markdown ценой оформления, без round-trip.
      */
     mode?: 'faithful' | 'readable';
+    /**
+     * Как ссылаться на аттачи:
+     *  - 'placeholder' (default) — {{img:name}} / {{file:name}} (для publish);
+     *  - 'local' — картинки как HTML `<img src="attachments/name">` (с
+     *    сохранением размеров), файлы как md-ссылки `[name](attachments/name)`.
+     *    Годится для самодостаточного просмотра рядом со скачанными файлами.
+     * Включение 'local' подразумевает readable-обработку текста.
+     */
+    attachments?: 'placeholder' | 'local';
+    /**
+     * Как выводить таблицы:
+     *  - 'auto' (default) — GFM (readable) / round-trip (faithful);
+     *  - 'records' — каждую строку разворачивать в запись
+     *    «**Заголовок:** значение», записи через `---`. Подразумевает readable.
+     */
+    tables?: 'auto' | 'records';
+    /** Префикс пути к локальным аттачам для attachments:'local'. Default: 'attachments/'. */
+    localPrefix?: string;
 }
 export interface StorageToMarkdownResult {
     markdown: string;

package/dist/export/to-markdown.js

@@ -28,7 +28,17 @@ import { compareStorage } from './canonical.js';
 import { decodeEntities, elements, getAttr, hasNamespacedElements, parseStorage, serializeStorage, textContent, } from './xhtml.js';
 /** Конвертирует storage-фрагмент страницы в Markdown. */
 export function storageToMarkdown(storage, opts = {}) {
-    const conv = new Converter(opts.registry ?? defaultMacroRegistry, opts.mode === 'readable');
+    const local = opts.attachments === 'local';
+    const records = opts.tables === 'records';
+    // 'local' и 'records' — заведомо не round-trip, поэтому включают readable-
+    // обработку текста (сущности, спаны, переносы), даже без mode:'readable'.
+    const readable = opts.mode === 'readable' || local || records;
+    const conv = new Converter(opts.registry ?? defaultMacroRegistry, {
+        readable,
+        localFiles: local,
+        tablesAsRecords: records,
+        localPrefix: opts.localPrefix ?? 'attachments/',
+    });
     const markdown = conv.blocksToMd(parseStorage(storage));
     const attachmentRefs = new Set([...conv.images, ...conv.files]);
     for (const m of storage.matchAll(/ri:filename="([^"]*)"/g))
@@ -67,13 +77,19 @@ const UNWRAP_BLOCK = new Set([
 const SAFE_URL_RE = /^[A-Za-z0-9\-._~:/?#@!$&'*+,;=%]+$/;
 class Converter {
     registry;
-    readable;
     images = new Set();
     files = new Set();
     stats = { markers: 0, fenced: 0, rawHtml: 0, lossy: 0 };
-    constructor(registry, readable = false) {
+    readable;
+    localFiles;
+    tablesAsRecords;
+    localPrefix;
+    constructor(registry, opts) {
         this.registry = registry;
-        this.readable = readable;
+        this.readable = opts.readable;
+        this.localFiles = opts.localFiles;
+        this.tablesAsRecords = opts.tablesAsRecords;
+        this.localPrefix = opts.localPrefix;
     }
     // ── Блочный уровень ──────────────────────────────────────────────────
     blocksToMd(nodes) {
@@ -104,7 +120,11 @@ class Converter {
         const h = /^h([1-6])$/.exec(el.name);
         try {
             if (h && el.attrs.length === 0) {
-                const inline = this.inlineToMd(el.children);
+                // Заголовок однострочен по определению — в readable схлопываем
+                // возможные переводы строк (из <br>) в пробел.
+                let inline = this.inlineToMd(el.children);
+                if (this.readable)
+                    inline = inline.replace(/\s*\n\s*/g, ' ');
                 if (inline.includes('\n') || inline.trim() === '')
                     throw new Unrepresentable();
                 return '#'.repeat(Number(h[1])) + ' ' + guardLineStart(inline.trim());
@@ -122,11 +142,15 @@ class Converter {
                 return '---';
             if (el.name === 'ul' || el.name === 'ol')
                 return this.listToMd(el);
-            // Простую таблицу — в чистый GFM (оба режима). Сложную tableToMd
-            // отклоняет: faithful → сырой HTML, readable → readableFallback
-            // (lossy++ и разворот в GFM через readableTable).
-            if (el.name === 'table')
+            if (el.name === 'table') {
+                // tables:'records' — любую таблицу разворачиваем в записи.
+                if (this.tablesAsRecords)
+                    return this.recordsTable(el);
+                // Простую таблицу — в чистый GFM (оба режима). Сложную tableToMd
+                // отклоняет: faithful → сырой HTML, readable → readableFallback
+                // (lossy++ и разворот в GFM через readableTable).
                 return this.tableToMd(el);
+            }
             if (el.name === 'ac:structured-macro')
                 return this.macroToMd(el);
             if (el.name === 'ac:image' || el.name === 'ac:link') {
@@ -147,7 +171,10 @@ class Converter {
         if (children.length === 0)
             return this.fallbackBlock(el);
         try {
-            const inline = this.inlineToMd(children).trim();
+            // multiline: в readable-абзаце <br> становится настоящим переводом
+            // строки (см. case 'br'). guardLineStart применяем к КАЖДОЙ строке —
+            // после переноса тоже нельзя случайно начать список/заголовок.
+            const inline = this.inlineToMd(children, { multiline: true }).trim();
             if (inline === '')
                 return this.fallbackBlock(el);
             // Абзац, начинающийся с блочного HTML-тега, markdown-it превратит в
@@ -155,7 +182,7 @@ class Converter {
             const m = /^<\/?([a-zA-Z][a-zA-Z0-9-]*)/.exec(inline);
             if (m && CM_BLOCK_TAGS.has(m[1].toLowerCase()))
                 return this.fallbackBlock(el);
-            return guardLineStart(inline);
+            return inline.split('\n').map((line) => guardLineStart(line)).join('\n');
         }
         catch (e) {
             if (!(e instanceof Unrepresentable))
@@ -255,9 +282,10 @@ class Converter {
                 .join('\n');
         }
         // p / td / th / li / caption и прочие «инлайн-контейнеры» → инлайн.
-        const inline = this.inlineToMd(el.children).trim();
+        // multiline: это свободный поток (не ячейка) — <br> станет переносом.
+        const inline = this.inlineToMd(el.children, { multiline: true }).trim();
         if (inline !== '')
-            return guardLineStart(inline);
+            return inline.split('\n').map((l) => guardLineStart(l)).join('\n');
         // Совсем ничего не вышло — голый текст (может быть пустым).
         return escapeMdText(textContent(el.children), {}, this.readable).trim();
     }
@@ -497,7 +525,7 @@ class Converter {
             content.every((n) => n.kind !== 'text' || /^[ \t\r\n]*$/.test(n.raw))) {
             content = els[0].children;
         }
-        const md = this.inlineToMd(content, { cell: false }).trim();
+        const md = this.inlineToMd(content, { cell: true }).trim();
         if (md.includes('\n'))
             throw new Unrepresentable();
         // Пайпы экранируем один раз над всей ячейкой — покрывает и текст, и
@@ -506,12 +534,12 @@ class Converter {
     }
     // ── Readable-таблицы: любая таблица → GFM ─────────────────────────────
     /**
-     * Разворачивает произвольную таблицу (colspan/rowspan, блочные ячейки,
-     * несколько header-строк) в GFM. Объединения превращаются в плотную
-     * сетку: содержимое — в верхней-левой клетке диапазона, остальные клетки
-     * пустые. Первая строка сетки становится шапкой GFM.
+     * Строит плотную сетку из произвольной таблицы (colspan/rowspan, блочные
+     * ячейки, несколько header-строк). Объединения раскрываются: содержимое —
+     * в верхней-левой клетке диапазона, остальные клетки пустые. Содержимое
+     * ячейки — flatten-строка БЕЗ экранирования пайпов (его делает вызывающий).
      */
-    readableTable(table) {
+    buildTableGrid(table) {
         const trs = [];
         let caption = '';
         for (const child of elements(table.children)) {
@@ -527,7 +555,6 @@ class Converter {
         }
         if (trs.length === 0)
             throw new Unrepresentable();
-        // Плотная сетка с учётом colspan/rowspan.
         const grid = [];
         const aligns = [];
         trs.forEach((tr, rowIdx) => {
@@ -541,10 +568,7 @@ class Converter {
                     col++;
                 const colspan = Math.max(1, Number(getAttr(cell, 'colspan') ?? '1') || 1);
                 const rowspan = Math.max(1, Number(getAttr(cell, 'rowspan') ?? '1') || 1);
-                // Экранируем пайпы ОДИН раз здесь — над всем содержимым ячейки
-                // (текст + плейсхолдеры {{img:…|…}} + буллеты), поэтому cellFlatten
-                // сам их не трогает (inline с cell:false).
-                const content = tidyCell(this.cellFlatten(cell.children)).replace(/\|/g, '\\|');
+                const content = tidyCell(this.cellFlatten(cell.children));
                 for (let r = 0; r < rowspan; r++) {
                     for (let c = 0; c < colspan; c++) {
                         const rr = rowIdx + r;
@@ -572,12 +596,45 @@ class Converter {
         }
         while (aligns.length < width)
             aligns.push('none');
+        return { grid, aligns, caption };
+    }
+    /** Разворачивает любую таблицу в GFM (сетка с заполнением объединений). */
+    readableTable(table) {
+        const { grid, aligns, caption } = this.buildTableGrid(table);
+        const esc = (s) => s.replace(/\|/g, '\\|');
         const sep = aligns.map((a) => a === 'left' ? ':---' : a === 'right' ? '---:' : a === 'center' ? ':---:' : '---');
-        const rowMd = (cells) => `| ${cells.join(' | ')} |`;
-        const lines = [rowMd(grid[0]), rowMd(sep), ...grid.slice(1).map(rowMd)];
+        const rowMd = (cells) => `| ${cells.map(esc).join(' | ')} |`;
+        const lines = [rowMd(grid[0]), `| ${sep.join(' | ')} |`, ...grid.slice(1).map(rowMd)];
         const table_ = lines.join('\n');
         return caption !== '' ? `**${caption}**\n\n${table_}` : table_;
     }
+    /**
+     * tables:'records' — каждую строку тела таблицы разворачивает в запись
+     * «**Заголовок:** значение» (пустые ячейки и колонки-филлеры пропускаются),
+     * записи разделяются `---`. Заголовки берутся из первой строки сетки.
+     */
+    recordsTable(table) {
+        this.stats.lossy++;
+        const { grid, caption } = this.buildTableGrid(table);
+        const header = grid[0];
+        const records = [];
+        for (const row of grid.slice(1)) {
+            const lines = [];
+            row.forEach((val, i) => {
+                const key = (header[i] ?? '').trim();
+                // В записи <br> из ячейки → «; » (одна строка, без HTML).
+                const value = val.replace(/<br>/g, '; ').trim();
+                if (key !== '' && value !== '')
+                    lines.push(`**${key}:** ${value}`);
+            });
+            if (lines.length > 0)
+                records.push(lines.join('\n'));
+        }
+        if (records.length === 0)
+            throw new Unrepresentable();
+        const body = records.join('\n\n---\n\n');
+        return caption !== '' ? `**${caption}**\n\n${body}` : body;
+    }
     /**
      * Сплющивает содержимое ячейки в одну строку: абзацы и пункты списков
      * разделяются `<br>` (единственный HTML, идиоматичный для GFM-ячеек),
@@ -590,7 +647,7 @@ class Converter {
         const flush = () => {
             if (inlineRun.length === 0)
                 return;
-            const s = this.inlineToMd(inlineRun, { cell: false }).replace(/\s+/g, ' ').trim();
+            const s = this.inlineToMd(inlineRun, { cell: true }).replace(/\s+/g, ' ').trim();
             if (s !== '')
                 blocks.push(s);
             inlineRun = [];
@@ -602,7 +659,7 @@ class Converter {
             }
             else if (n.kind === 'el' && n.name === 'p') {
                 flush();
-                const s = this.inlineToMd(n.children, { cell: false }).replace(/\s+/g, ' ').trim();
+                const s = this.inlineToMd(n.children, { cell: true }).replace(/\s+/g, ' ').trim();
                 if (s !== '')
                     blocks.push(s);
             }
@@ -735,6 +792,11 @@ class Converter {
                 return `${ticks}${pad}${text}${pad}${ticks}`;
             }
             case 'br':
+                // readable: в свободном потоке (абзац/цитата) — настоящий перенос
+                // строки; в ячейке GFM-таблицы перенос невозможен (сломал бы строку
+                // таблицы) — там остаётся <br>. faithful — всегда <br/> (round-trip).
+                if (this.readable)
+                    return ctx.multiline ? '\n' : ctx.cell ? '<br>' : '<br/>';
                 return '<br/>';
             case 'a':
                 return this.linkAnchorToMd(el, ctx);
@@ -807,6 +869,30 @@ class Converter {
         if (kids.length !== 1)
             throw new Unrepresentable();
         const ref = kids[0];
+        // attachments:'local' — картинка как HTML <img> (сохраняет размеры).
+        // ri:attachment → локальный путь; ri:url → внешний URL как есть.
+        if (this.localFiles && (ref.name === 'ri:attachment' || ref.name === 'ri:url')) {
+            let src;
+            let alt = '';
+            if (ref.name === 'ri:attachment') {
+                const filename = getAttr(ref, 'ri:filename') ?? '';
+                this.images.add(filename);
+                src = this.localPrefix + filename;
+                alt = filename;
+            }
+            else {
+                src = getAttr(ref, 'ri:value') ?? '';
+            }
+            const attrs = [['src', escapeXmlAttr(src)]];
+            for (const [k] of el.attrs) {
+                const plain = k.startsWith('ac:') ? k.slice(3) : k;
+                if (plain === 'height' || plain === 'width') {
+                    attrs.push([plain, escapeXmlAttr(getAttr(el, k) ?? '')]);
+                }
+            }
+            attrs.push(['alt', escapeXmlAttr(alt)]);
+            return serializeStorage([{ kind: 'el', name: 'img', attrs, children: [], selfClosing: true }]);
+        }
         if (ref.name === 'ri:url') {
             if (ref.attrs.some(([k]) => k !== 'ri:value'))
                 throw new Unrepresentable();
@@ -881,8 +967,15 @@ class Converter {
                 throw new Unrepresentable();
             }
             const filename = getAttr(ref, 'ri:filename') ?? '';
-            badPlaceholderPart(filename);
             this.files.add(filename);
+            // attachments:'local' — md-ссылка на локальный файл вместо {{file:}}.
+            if (this.localFiles) {
+                const label = (text ?? filename).replace(/[[\]]/g, '\\$&');
+                const path = this.localPrefix + filename;
+                const target = /[()\s]/.test(path) ? `<${path}>` : path;
+                return `[${label}](${target})`;
+            }
+            badPlaceholderPart(filename);
             return `{{file:${filename}${textAttr}}}`;
         }
         throw new Unrepresentable();
@@ -1059,21 +1152,13 @@ function escapeMdText(raw, ctx, readable = false) {
     out += escapePlain(collapsed.slice(last), ctx, readable);
     return out;
 }
-function escapePlain(s, ctx, readable = false) {
-    let esc = s.replace(/[\\`*_[\]{}~]/g, (c) => '\\' + c);
-    if (readable) {
-        // readable: неразрывный пробел → обычный (чище на вид).
-        esc = esc.replace(/\u00A0/g, ' ');
-        if (ctx.cell)
-            esc = esc.replace(/\|/g, '\\|');
-        return esc;
-    }
-    // Сырой U+00A0 на краю абзаца съедается trim()'ом markdown-it —
-    // в entity-форме переживает рендер (и виден при редактировании).
-    esc = esc.replace(/\u00A0/g, '&nbsp;');
-    if (ctx.cell)
-        esc = esc.replace(/\|/g, '\\|');
-    return esc;
+function escapePlain(s, _ctx, readable = false) {
+    const esc = s.replace(/[\\`*_[\]{}~]/g, (c) => '\\' + c);
+    // Пайпы здесь НЕ трогаем — они экранируются один раз на границе ячейки
+    // (cellMd / readableTable), иначе плейсхолдеры {{img:…|…}} двоились бы.
+    // readable: неразрывный пробел → обычный; faithful: → entity (переживает
+    // trim() markdown-it на краю абзаца).
+    return esc.replace(/\u00A0/g, readable ? ' ' : '&nbsp;');
 }
 /** Экранирует конструкции, значимые в начале строки (#, >, -, 1. …). */
 function guardLineStart(md) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-md-sync",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
   "keywords": [
     "confluence",