confluence-md-sync 0.4.1 → 0.5.0

package/README.md

@@ -199,6 +199,10 @@ console.log(downloaded);               // Map<filename, localPath> of saved atta
 
 // 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*:
@@ -228,13 +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
-# 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
+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) {
@@ -126,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') {
@@ -514,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)) {
@@ -535,7 +555,6 @@ class Converter {
         }
         if (trs.length === 0)
             throw new Unrepresentable();
-        // Плотная сетка с учётом colspan/rowspan.
         const grid = [];
         const aligns = [];
         trs.forEach((tr, rowIdx) => {
@@ -549,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;
@@ -580,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-ячеек),
@@ -820,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();
@@ -894,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-md-sync",
-  "version": "0.4.1",
+  "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",