confluence-md-sync 0.4.0 → 0.4.1

package/README.md

@@ -180,18 +180,24 @@ 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);
 ```
 
@@ -225,6 +231,7 @@ normalised away (Confluence itself rewrites these on every save). Use
 From the CLI:
 
 ```bash
+# 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

package/dist/export/to-markdown.js

@@ -104,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());
@@ -147,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 превратит в
@@ -155,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))
@@ -255,9 +262,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 +505,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();
         // Пайпы экранируем один раз над всей ячейкой — покрывает и текст, и
@@ -590,7 +598,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 +610,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 +743,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);
@@ -1059,21 +1072,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.4.1",
   "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
   "keywords": [
     "confluence",