confluence-md-sync 0.3.0 → 0.4.1

package/README.md

@@ -28,9 +28,9 @@ npm install -g confluence-md-sync       # as a CLI: `confluence-md-sync …`
 - **Flexible sources** — images/files accept relative paths, absolute paths
   or `http(s)` URLs; URLs on your Confluence host are fetched with the
   configured token.
-- **Loss-free round-trip** — export a page to Markdown and publish it back;
-  what Markdown can't express is kept verbatim, verified by canonical
-  storage comparison.
+- **Export & round-trip** — pull a page into Markdown and publish it back
+  loss-free (verified by canonical storage comparison), or export a
+  `readable`, pure-Markdown version for humans.
 
 ## Configuration
 
@@ -171,23 +171,34 @@ import { convertBpmnFolder } from 'confluence-md-sync';
 await convertBpmnFolder({ srcDir: 'docs/diagrams', outDir: 'build' });
 ```
 
-## Export a page back to Markdown (round-trip)
+## Export a page back to Markdown
 
-Pull an existing page by ID and turn its storage format into Markdown —
-without losing markup. The conversion is **loss-free by construction**: a
-three-tier policy renders each node as clean Markdown where possible,
-macro markers where a macro round-trips, and verbatim storage (raw HTML,
-or a ` ```confluence-storage ` fence) as a fallback. Attachments and page
-links become `{{img:...}}` / `{{file:...}}` / `{{page:...}}` placeholders.
+Pull an existing page by ID and turn its storage format into Markdown.
+Attachments and page links become `{{img:...}}` / `{{file:...}}` /
+`{{page:...}}` placeholders. Two modes trade fidelity against readability:
+
+| 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, 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' },   // writes exported/page.md + exported/attachments/
+  { outDir: 'exported' },              // faithful; exported/page.md + exported/attachments/
   cfg,
 );
+console.log(downloaded);               // Map<filename, localPath> of saved attachments
+
+// Readable variant for humans (writes page.md + ./attachments/ next to it):
+await exportPage('123456789', { outFile: 'page.md', mode: 'readable' }, cfg);
 ```
 
 Round-trip means *edit the Markdown, then publish it straight back*:
@@ -220,8 +231,10 @@ normalised away (Confluence itself rewrites these on every save). Use
 From the CLI:
 
 ```bash
-confluence-md-sync export    123456789 --out-dir exported
-confluence-md-sync roundtrip 123456789 --show-markdown   # exit 2 on loss
+# attachments download to ./attachments/ next to the .md (omit --no-attachments)
+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
 ```
 
 ## Read pages and tables
@@ -321,7 +334,8 @@ export CONFLUENCE_BASE_URL='https://confluence.example.com'
 export CONFLUENCE_TOKEN='<your-PAT>'
 
 # Download a page to an exact .md path (add --no-attachments for the md only)
-confluence-md-sync export 123456789 --out ./page.md
+confluence-md-sync export 123456789 --out ./page.md              # faithful
+confluence-md-sync export 123456789 --out ./page.md --readable   # clean Markdown
 
 confluence-md-sync publish docs/page.md --page-id 123456789 \
   --image build/flow.png --file build/data.csv --label docs

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>] [--no-attachments]
+  confluence-md-sync export    <page-id> [--out <file> | --out-dir <dir>] [--readable] [--no-attachments]
   confluence-md-sync roundtrip <page-id> [--show-markdown]
 
 publish options:
@@ -43,6 +43,9 @@ export options:
                         if any, go to attachments/ next to it)
   --out-dir <dir>       Output directory (default: ./<page-id>); writes page.md
                         and attachments/
+  --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
   --no-attachments      Do not download referenced attachments
 
 roundtrip options:
@@ -70,6 +73,7 @@ async function main() {
             'dry-run': { type: 'boolean' },
             out: { type: 'string' },
             'out-dir': { type: 'string' },
+            readable: { type: 'boolean' },
             'no-attachments': { type: 'boolean' },
             'show-markdown': { type: 'boolean' },
             help: { type: 'boolean' },
@@ -107,9 +111,13 @@ async function main() {
             outFile: values.out,
             outDir: values['out-dir'],
             downloadAttachments: !values['no-attachments'],
+            mode: values.readable ? 'readable' : 'faithful',
         }, cfg);
+        const tail = values.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}` +
-            ` (${result.downloaded.size} attachment(s), ${result.stats.fenced} raw storage block(s))`);
+            ` (${result.downloaded.size} attachment(s), ${tail})`);
         return;
     }
     if (command === 'roundtrip') {

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

@@ -18,6 +18,11 @@ export interface ExportPageOptions {
     outDir?: string;
     /** Скачивать ли аттачи, на которые ссылается страница. Default: true. */
     downloadAttachments?: boolean;
+    /**
+     * 'faithful' (default) — round-trippable, с сырым HTML в fallback;
+     * 'readable' — чистый Markdown ценой оформления (round-trip не гарантирован).
+     */
+    mode?: 'faithful' | 'readable';
     registry?: MacroRegistry;
 }
 export interface ExportPageResult extends StorageToMarkdownResult {

package/dist/export/export-page.js

@@ -9,7 +9,7 @@ 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 });
+    const converted = storageToMarkdown(page.storage, { registry: opts.registry, mode: opts.mode });
     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

@@ -1,23 +1,33 @@
 /**
- * Конвертация Confluence storage → Markdown с гарантией round-trip.
+ * Конвертация Confluence storage → Markdown. Два режима:
  *
- * Трёхуровневая политика на каждый узел:
+ * FAITHFUL (default) — гарантия round-trip. Трёхуровневая политика:
  *  1. чистый Markdown — заголовки, абзацы, списки, простые таблицы,
  *     ссылки, картинки-аттачи ({{img:...}}), page-ссылки ({{page:...}});
  *  2. маркеры макросов <!-- MACRO:start/end --> — для макросов, чей
  *     рендер восстанавливает исходный XHTML (проверяется на месте:
  *     маркер прогоняется через render-конвейер и сравнивается канонически);
- *  3. дословный XHTML — «как есть»: без ac:/ri:-тегов — сырым HTML
- *     (markdown-it пропускает его насквозь), с ними — fenced-блоком
- *     ```confluence-storage (разворачивается обратно при рендере).
+ *  3. дословный XHTML — «как есть»: без ac:/ri:-тегов — сырым HTML,
+ *     с ними — fenced-блоком ```confluence-storage.
+ *  Потери исключены по построению; но (3) даёт сырой HTML, который многие
+ *  md-редакторы показывают уродливо.
  *
- * Потери по построению исключены: всё, что не легло в (1)-(2), уезжает
- * в (3) дословно.
+ * READABLE — чистый Markdown ценой оформления. Round-trip НЕ гарантируется:
+ *  теряются цвета/стили спанов, div-обёртки, точная геометрия объединённых
+ *  ячеек; сохраняется смысловая нагрузка (текст, структура). Сложные
+ *  таблицы разворачиваются в GFM (colspan/rowspan → сетка с заполнением,
+ *  блочное содержимое ячеек — во flatten через <br>). Сырой HTML-блок не
+ *  выдаётся никогда.
  */
 import { type MacroRegistry } from '../macros/registry.js';
 export interface StorageToMarkdownOptions {
     /** Реестр для проверки маркеров макросов (default: встроенный). */
     registry?: MacroRegistry;
+    /**
+     * 'faithful' (default) — round-trippable, но с сырым HTML в fallback;
+     * 'readable' — чистый Markdown ценой оформления, без round-trip.
+     */
+    mode?: 'faithful' | 'readable';
 }
 export interface StorageToMarkdownResult {
     markdown: string;
@@ -31,6 +41,8 @@ export interface StorageToMarkdownResult {
         markers: number;
         fenced: number;
         rawHtml: number;
+        /** readable-режим: сколько узлов конвертировано с потерей оформления. */
+        lossy: number;
     };
 }
 /** Конвертирует storage-фрагмент страницы в Markdown. */

package/dist/export/to-markdown.js

@@ -1,18 +1,23 @@
 /**
- * Конвертация Confluence storage → Markdown с гарантией round-trip.
+ * Конвертация Confluence storage → Markdown. Два режима:
  *
- * Трёхуровневая политика на каждый узел:
+ * FAITHFUL (default) — гарантия round-trip. Трёхуровневая политика:
  *  1. чистый Markdown — заголовки, абзацы, списки, простые таблицы,
  *     ссылки, картинки-аттачи ({{img:...}}), page-ссылки ({{page:...}});
  *  2. маркеры макросов <!-- MACRO:start/end --> — для макросов, чей
  *     рендер восстанавливает исходный XHTML (проверяется на месте:
  *     маркер прогоняется через render-конвейер и сравнивается канонически);
- *  3. дословный XHTML — «как есть»: без ac:/ri:-тегов — сырым HTML
- *     (markdown-it пропускает его насквозь), с ними — fenced-блоком
- *     ```confluence-storage (разворачивается обратно при рендере).
+ *  3. дословный XHTML — «как есть»: без ac:/ri:-тегов — сырым HTML,
+ *     с ними — fenced-блоком ```confluence-storage.
+ *  Потери исключены по построению; но (3) даёт сырой HTML, который многие
+ *  md-редакторы показывают уродливо.
  *
- * Потери по построению исключены: всё, что не легло в (1)-(2), уезжает
- * в (3) дословно.
+ * READABLE — чистый Markdown ценой оформления. Round-trip НЕ гарантируется:
+ *  теряются цвета/стили спанов, div-обёртки, точная геометрия объединённых
+ *  ячеек; сохраняется смысловая нагрузка (текст, структура). Сложные
+ *  таблицы разворачиваются в GFM (colspan/rowspan → сетка с заполнением,
+ *  блочное содержимое ячеек — во flatten через <br>). Сырой HTML-блок не
+ *  выдаётся никогда.
  */
 import { macro } from '../macros/builder.js';
 import { escapeXmlAttr } from '../macros/xml.js';
@@ -23,7 +28,7 @@ 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);
+    const conv = new Converter(opts.registry ?? defaultMacroRegistry, opts.mode === 'readable');
     const markdown = conv.blocksToMd(parseStorage(storage));
     const attachmentRefs = new Set([...conv.images, ...conv.files]);
     for (const m of storage.matchAll(/ri:filename="([^"]*)"/g))
@@ -52,14 +57,23 @@ const CM_BLOCK_TAGS = new Set([
     'pre', 'script', 'style', 'textarea',
 ]);
 const INLINE_RAW_WRAP = new Set(['span', 'u', 'sub', 'sup', 'small', 'big', 'font', 'del', 'ins', 'abbr', 'cite', 'q', 'mark', 'time']);
+// Блочные контейнеры-обёртки: в readable-режиме разворачиваются (их дети
+// обрабатываются как блоки), сам тег и его атрибуты отбрасываются.
+const UNWRAP_BLOCK = new Set([
+    'div', 'section', 'article', 'aside', 'figure', 'figcaption', 'header',
+    'footer', 'main', 'nav', 'center', 'details', 'summary',
+    'ac:layout', 'ac:layout-section', 'ac:layout-cell',
+]);
 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 };
-    constructor(registry) {
+    stats = { markers: 0, fenced: 0, rawHtml: 0, lossy: 0 };
+    constructor(registry, readable = false) {
         this.registry = registry;
+        this.readable = readable;
     }
     // ── Блочный уровень ──────────────────────────────────────────────────
     blocksToMd(nodes) {
@@ -90,7 +104,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());
@@ -108,6 +126,9 @@ 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')
                 return this.tableToMd(el);
             if (el.name === 'ac:structured-macro')
@@ -130,7 +151,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 превратит в
@@ -138,7 +162,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))
@@ -153,6 +177,8 @@ class Converter {
      * а рендер вернёт плейсхолдерам исходную ac:-форму.
      */
     fallbackBlock(el) {
+        if (this.readable)
+            return this.readableFallback(el);
         const direct = this.tryRawHtml(el);
         if (direct !== null)
             return direct;
@@ -204,14 +230,82 @@ class Converter {
         const ticks = '`'.repeat(Math.max(3, ...runs.map((r) => r.length + 1)));
         return `${ticks}confluence-storage\n${content}\n${ticks}`;
     }
+    // ── Readable-режим: lossy-конвертация в чистый Markdown ────────────────
+    /**
+     * Fallback readable-режима: НИКОГДА не выдаёт сырой HTML-блок. Таблицы
+     * разворачивает в GFM, контейнеры-обёртки — в блоки, blockquote — в `>`,
+     * остальное — в инлайн/текст. Content сохраняется, оформление теряется.
+     */
+    readableFallback(el) {
+        this.stats.lossy++;
+        const name = el.name.toLowerCase();
+        if (el.name === 'table') {
+            try {
+                return this.readableTable(el);
+            }
+            catch (e) {
+                if (!(e instanceof Unrepresentable))
+                    throw e;
+            }
+        }
+        if (UNWRAP_BLOCK.has(name)) {
+            const inner = this.blocksToMd(el.children).trimEnd();
+            if (inner !== '')
+                return inner;
+            return '';
+        }
+        if (name === 'blockquote') {
+            const inner = this.blocksToMd(el.children).trimEnd();
+            return inner
+                .split('\n')
+                .map((line) => (line === '' ? '>' : `> ${line}`))
+                .join('\n');
+        }
+        // p / td / th / li / caption и прочие «инлайн-контейнеры» → инлайн.
+        // multiline: это свободный поток (не ячейка) — <br> станет переносом.
+        const inline = this.inlineToMd(el.children, { multiline: true }).trim();
+        if (inline !== '')
+            return inline.split('\n').map((l) => guardLineStart(l)).join('\n');
+        // Совсем ничего не вышло — голый текст (может быть пустым).
+        return escapeMdText(textContent(el.children), {}, this.readable).trim();
+    }
     // ── Макросы ──────────────────────────────────────────────────────────
     macroToMd(el) {
         const name = getAttr(el, 'ac:name') ?? '';
         const markerMd = this.tryMacroMarker(el, name);
-        if (markerMd === null)
-            return this.fence(serializeStorage([el]));
-        this.stats.markers++;
-        return markerMd;
+        if (markerMd !== null) {
+            this.stats.markers++;
+            return markerMd;
+        }
+        if (this.readable)
+            return this.readableMacro(el);
+        return this.fence(serializeStorage([el]));
+    }
+    /**
+     * Readable-режим для макроса, который не лёг в маркер: сохраняем
+     * содержимое, теряем «обёртку» макроса. rich-text-body → блоки;
+     * plain-text-body → код-fence (обычный ``` — чистый Markdown);
+     * иначе — заголовок-подпись, чтобы место макроса не исчезло бесследно.
+     */
+    readableMacro(el) {
+        this.stats.lossy++;
+        const name = getAttr(el, 'ac:name') ?? 'macro';
+        for (const child of elements(el.children)) {
+            if (child.name === 'ac:rich-text-body') {
+                const inner = this.blocksToMd(child.children).trimEnd();
+                if (inner !== '')
+                    return inner;
+            }
+            if (child.name === 'ac:plain-text-body') {
+                const text = textContent(child.children);
+                if (text.trim() !== '') {
+                    const ticks = '`'.repeat(Math.max(3, ...(text.match(/`+/g) ?? []).map((r) => r.length + 1)));
+                    return `${ticks}\n${text}\n${ticks}`;
+                }
+            }
+        }
+        // Bodyless-макрос (toc, children, …) — оставляем видимый след.
+        return `_[macro: ${name}]_`;
     }
     /**
      * Пытается выразить макрос маркером. Возвращает null, если параметры
@@ -414,7 +508,137 @@ class Converter {
         const md = this.inlineToMd(content, { cell: true }).trim();
         if (md.includes('\n'))
             throw new Unrepresentable();
-        return md;
+        // Пайпы экранируем один раз над всей ячейкой — покрывает и текст, и
+        // плейсхолдеры {{img:…|…}} (которые минуют инлайн-экранирование).
+        return md.replace(/\|/g, '\\|');
+    }
+    // ── Readable-таблицы: любая таблица → GFM ─────────────────────────────
+    /**
+     * Разворачивает произвольную таблицу (colspan/rowspan, блочные ячейки,
+     * несколько header-строк) в GFM. Объединения превращаются в плотную
+     * сетку: содержимое — в верхней-левой клетке диапазона, остальные клетки
+     * пустые. Первая строка сетки становится шапкой GFM.
+     */
+    readableTable(table) {
+        const trs = [];
+        let caption = '';
+        for (const child of elements(table.children)) {
+            if (child.name === 'caption')
+                caption = this.inlineToMd(child.children).trim();
+            else if (['thead', 'tbody', 'tfoot'].includes(child.name)) {
+                for (const tr of elements(child.children))
+                    if (tr.name === 'tr')
+                        trs.push(tr);
+            }
+            else if (child.name === 'tr')
+                trs.push(child);
+        }
+        if (trs.length === 0)
+            throw new Unrepresentable();
+        // Плотная сетка с учётом colspan/rowspan.
+        const grid = [];
+        const aligns = [];
+        trs.forEach((tr, rowIdx) => {
+            if (!grid[rowIdx])
+                grid[rowIdx] = [];
+            let col = 0;
+            for (const cell of elements(tr.children)) {
+                if (cell.name !== 'td' && cell.name !== 'th')
+                    continue;
+                while (grid[rowIdx][col] !== undefined)
+                    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, '\\|');
+                for (let r = 0; r < rowspan; r++) {
+                    for (let c = 0; c < colspan; c++) {
+                        const rr = rowIdx + r;
+                        const cc = col + c;
+                        if (!grid[rr])
+                            grid[rr] = [];
+                        grid[rr][cc] = r === 0 && c === 0 ? content : '';
+                    }
+                }
+                if (rowIdx === 0) {
+                    const a = readableAlign(cell);
+                    for (let c = 0; c < colspan; c++)
+                        aligns[col + c] = a;
+                }
+                col += colspan;
+            }
+        });
+        const width = Math.max(...grid.map((r) => r.length));
+        if (width === 0)
+            throw new Unrepresentable();
+        for (const r of grid) {
+            for (let c = 0; c < width; c++)
+                if (r[c] === undefined)
+                    r[c] = '';
+        }
+        while (aligns.length < width)
+            aligns.push('none');
+        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 table_ = lines.join('\n');
+        return caption !== '' ? `**${caption}**\n\n${table_}` : table_;
+    }
+    /**
+     * Сплющивает содержимое ячейки в одну строку: абзацы и пункты списков
+     * разделяются `<br>` (единственный HTML, идиоматичный для GFM-ячеек),
+     * пункты помечаются `• `. Инлайн-разметка (жирный, ссылки, плейсхолдеры)
+     * сохраняется.
+     */
+    cellFlatten(nodes) {
+        const blocks = [];
+        let inlineRun = [];
+        const flush = () => {
+            if (inlineRun.length === 0)
+                return;
+            const s = this.inlineToMd(inlineRun, { cell: true }).replace(/\s+/g, ' ').trim();
+            if (s !== '')
+                blocks.push(s);
+            inlineRun = [];
+        };
+        for (const n of nodes) {
+            if (n.kind === 'el' && (n.name === 'ul' || n.name === 'ol')) {
+                flush();
+                blocks.push(this.flattenList(n));
+            }
+            else if (n.kind === 'el' && n.name === 'p') {
+                flush();
+                const s = this.inlineToMd(n.children, { cell: true }).replace(/\s+/g, ' ').trim();
+                if (s !== '')
+                    blocks.push(s);
+            }
+            else if (n.kind === 'el' && (UNWRAP_BLOCK.has(n.name.toLowerCase()) || n.name === 'blockquote')) {
+                flush();
+                const s = this.cellFlatten(n.children);
+                if (s !== '')
+                    blocks.push(s);
+            }
+            else if (n.kind === 'el' && n.name === 'table') {
+                flush();
+                const s = this.cellFlatten(collectCellText(n));
+                if (s !== '')
+                    blocks.push(s);
+            }
+            else {
+                inlineRun.push(n);
+            }
+        }
+        flush();
+        return blocks.filter((b) => b !== '').join('<br>');
+    }
+    flattenList(list) {
+        const items = elements(list.children).filter((li) => li.name === 'li');
+        return items
+            .map((li) => '• ' + this.cellFlatten(li.children))
+            .filter((s) => s !== '• ')
+            .join('<br>');
     }
     // ── Инлайн ───────────────────────────────────────────────────────────
     /**
@@ -471,12 +695,19 @@ class Converter {
         let out = '';
         for (const n of this.normalizeInline(nodes)) {
             if (n.kind === 'text') {
-                out += escapeMdText(n.raw, ctx);
+                out += escapeMdText(n.raw, ctx, this.readable);
                 continue;
             }
-            if (n.kind === 'cdata')
+            if (n.kind === 'cdata') {
+                if (this.readable) {
+                    out += escapeMdText(n.text, ctx, true);
+                    continue;
+                }
                 throw new Unrepresentable();
+            }
             if (n.kind === 'comment') {
+                if (this.readable)
+                    continue; // невидимый комментарий — отбрасываем
                 if (n.text.includes('MACRO:') || n.text.includes('-->'))
                     throw new Unrepresentable();
                 out += `<!--${n.text}-->`;
@@ -492,24 +723,31 @@ class Converter {
                 return this.wrapInline(el, '**', ctx);
             case 'em':
                 return this.wrapInline(el, '*', ctx);
-            // <b>/<i> оставляем сырым HTML: ** рендерится в <strong>, а не в <b>.
+            // <b>/<i>: faithful — сырой HTML (** рендерится в <strong>, а не <b>);
+            // readable — маппим в **/* (потеря точного тега приемлема).
             case 'b':
+                return this.readable ? this.wrapInline(el, '**', ctx) : this.rawInline(el, ctx);
             case 'i':
-                return this.rawInline(el, ctx);
+                return this.readable ? this.wrapInline(el, '*', ctx) : this.rawInline(el, ctx);
             case 's':
                 return this.wrapInline(el, '~~', ctx);
             case 'code': {
-                if (el.attrs.length > 0)
-                    throw new Unrepresentable();
-                const text = textContent(el.children);
-                if (text.includes('\n') || text.trim() === '')
+                if (el.attrs.length > 0 && !this.readable)
                     throw new Unrepresentable();
+                const text = textContent(el.children).replace(/\s*\n\s*/g, ' ');
+                if (text.trim() === '')
+                    return this.readable ? '' : (() => { throw new Unrepresentable(); })();
                 const runs = text.match(/`+/g) ?? [];
                 const ticks = '`'.repeat(Math.max(1, ...runs.map((r) => r.length + 1)));
                 const pad = text.startsWith('`') || text.endsWith('`') || text.startsWith(' ') || text.endsWith(' ') ? ' ' : '';
                 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);
@@ -517,35 +755,42 @@ class Converter {
                 const src = getAttr(el, 'src') ?? '';
                 const alt = getAttr(el, 'alt') ?? '';
                 const other = el.attrs.filter(([k]) => k !== 'src' && k !== 'alt');
-                if (other.length === 0 && SAFE_URL_RE.test(src) && !/[[\]()]/.test(alt)) {
-                    return `![${alt}](${src})`;
+                if ((other.length === 0 || this.readable) && SAFE_URL_RE.test(src) && !/[[\]()]/.test(alt)) {
+                    return `![${alt}](${src})`; // readable: лишние атрибуты (class…) отбрасываются
                 }
-                return this.rawInline(el, ctx);
+                return this.readable ? escapeMdText(alt, ctx, true) : this.rawInline(el, ctx);
             }
             case 'ac:image':
                 return this.acImageToMd(el);
             case 'ac:link':
                 return this.acLinkToMd(el);
             default:
+                // readable: любой не-ac инлайн-контейнер (span, u, sub, font, …)
+                // разворачиваем — тег и стили теряем, содержимое оставляем.
+                if (this.readable && !el.name.includes(':'))
+                    return this.inlineToMd(el.children, ctx);
+                if (this.readable)
+                    return escapeMdText(textContent(el.children), ctx, true);
                 if (INLINE_RAW_WRAP.has(el.name))
                     return this.rawInline(el, ctx);
                 throw new Unrepresentable();
         }
     }
     wrapInline(el, marker, ctx) {
-        if (el.attrs.length > 0)
+        if (el.attrs.length > 0 && !this.readable)
             return this.rawInline(el, ctx);
         const inner = this.inlineToMd(el.children, ctx);
         // Краевые ПРОСТЫЕ пробелы выносим наружу — `**текст **` маркдауном не
         // является. Юникодные пробелы (&nbsp; и т.п.) выносить нельзя (изменит
         // содержимое), а внутри маркеров они ломают flanking-правила — такой
-        // элемент отдаём сырым HTML.
+        // элемент отдаём сырым HTML (faithful) либо просто оставляем как есть
+        // без обёртки (readable).
         const m = /^([ \t]*)([\s\S]*?)([ \t]*)$/.exec(inner);
         if (!m || m[2] === '')
             return inner;
         const decodedEdges = decodeEntities(m[2]);
         if (/^\s|\s$/u.test(decodedEdges))
-            return this.rawInline(el, ctx);
+            return this.readable ? inner : this.rawInline(el, ctx);
         return `${m[1]}${marker}${m[2]}${marker}${m[3]}`;
     }
     /** Инлайн-элемент дословно: открывающий тег + инлайн-дети + закрывающий. */
@@ -562,9 +807,12 @@ class Converter {
     linkAnchorToMd(el, ctx) {
         const href = getAttr(el, 'href') ?? '';
         const inner = this.inlineToMd(el.children, ctx);
-        if (el.attrs.length === 1 && el.attrs[0][0] === 'href' && SAFE_URL_RE.test(href) && !/[[\]]/.test(inner)) {
-            return `[${inner}](${href})`;
+        const onlyHref = el.attrs.length === 1 && el.attrs[0][0] === 'href';
+        if ((onlyHref || this.readable) && SAFE_URL_RE.test(href) && !/[[\]]/.test(inner)) {
+            return `[${inner}](${href})`; // readable: доп. атрибуты ссылки отбрасываются
         }
+        if (this.readable)
+            return inner; // ссылку не выразить в MD — оставляем текст
         return this.rawInline(el, ctx);
     }
     acImageToMd(el) {
@@ -801,26 +1049,36 @@ const ENTITY_RE = /&(?:#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g;
  * Экранирует markdown-активные символы, сохраняя сущности (&nbsp; и т.п.)
  * как есть — markdown-it декодирует их при рендере.
  */
-function escapeMdText(raw, ctx) {
+function escapeMdText(raw, ctx, readable = false) {
     const collapsed = raw.replace(/[\r\n]+/g, ' ');
     let out = '';
     let last = 0;
     for (const m of collapsed.matchAll(ENTITY_RE)) {
-        out += escapePlain(collapsed.slice(last, m.index), ctx);
-        out += m[0];
+        out += escapePlain(collapsed.slice(last, m.index), ctx, readable);
+        if (readable) {
+            // readable: декодируем сущность в символ (&quot;→", &mdash;→—, nbsp→
+            // пробел). `<`, `>`, `&` оставляем сущностями — их «живой» символ
+            // мог бы создать случайный HTML/сущность. Нераспознанное — как есть.
+            const dec = decodeEntities(m[0]);
+            out += dec === m[0] || dec === '<' || dec === '>' || dec === '&'
+                ? m[0]
+                : escapePlain(dec, ctx, readable);
+        }
+        else {
+            out += m[0];
+        }
         last = m.index + m[0].length;
     }
-    out += escapePlain(collapsed.slice(last), ctx);
+    out += escapePlain(collapsed.slice(last), ctx, readable);
     return out;
 }
-function escapePlain(s, ctx) {
-    let esc = s.replace(/[\\`*_[\]{}~]/g, (c) => '\\' + c);
-    // Сырой U+00A0 на краю абзаца съедается trim()'ом markdown-it —
-    // в entity-форме переживает рендер (и виден при редактировании).
-    esc = esc.replace(/ /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) {
@@ -843,3 +1101,37 @@ function cellAlign(cell) {
         throw new Unrepresentable();
     return m[1];
 }
+/** Как cellAlign, но не бросает: любой нераспознанный стиль → 'none'. */
+function readableAlign(cell) {
+    const style = getAttr(cell, 'style');
+    const m = style ? /text-align:\s*(left|right|center)/.exec(style) : null;
+    return m ? m[1] : 'none';
+}
+/**
+ * Причёсывает содержимое GFM-ячейки: нормализует `<br/>`→`<br>`, схлопывает
+ * подряд идущие переводы строк и срезает их по краям — чтобы «пустая»
+ * ячейка (в исходнике `<p><br/></p>`) стала действительно пустой.
+ */
+function tidyCell(s) {
+    return s
+        .replace(/<br\s*\/?>/gi, '<br>')
+        .replace(/(?:\s*<br>\s*)+/g, '<br>')
+        .replace(/^<br>|<br>$/g, '')
+        .trim();
+}
+/** Разворачивает вложенную в ячейку таблицу в плоский список её ячеек. */
+function collectCellText(table) {
+    const out = [];
+    const walk = (nodes) => {
+        for (const n of nodes) {
+            if (n.kind === 'el' && (n.name === 'td' || n.name === 'th')) {
+                out.push({ kind: 'el', name: 'p', attrs: [], children: n.children, selfClosing: false });
+            }
+            else if (n.kind === 'el') {
+                walk(n.children);
+            }
+        }
+    };
+    walk(table.children);
+    return out;
+}

package/package.json

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