confluence-md-sync 0.11.2 → 0.13.0

package/README.md

@@ -496,3 +496,19 @@ the `v*` tag triggers the npm publish workflow (tag must match
 ## License
 
 [MIT](LICENSE)
+
+### Inline Note and native image formatting
+
+`{{note:Required category}}` works in prose and GFM cells. Nested `{{page:…}}`,
+`{{jira:…}}` and `{{file:…}}` stay editable. Escape literal `|`, `{`, `}`, `:` with
+backslashes. A newline (or `\n` in a plain body) creates a paragraph; `<br>` keeps
+a line break within the same paragraph. For parameters or a multi-paragraph cell,
+use a JSON-quoted body: `{{note:"First\nSecond<br>line"|title=Context|icon=false}}`.
+Block `> [!NOTE]` is unchanged. Complex imported cell Notes retain storage losslessly.
+
+Native attachment images forward Confluence image parameters: width/height, align,
+border, thumbnail, title (Data Center caption), alt, hspace/vspace, class/style and
+queryparams (effects). `link=https://…` hyperlinks an image; `display=link` displays
+the attachment as a link. Structurizr and optional draw.io image mode share these
+parameters; draw.io uses its native macro by default. Values containing separators
+can use JSON quotes. Browser-safe authoring helpers are exported from `/syntax`.

package/dist/export/to-markdown.js

@@ -24,6 +24,9 @@ import { escapeXmlAttr } from '../macros/xml.js';
 import { processMacros } from '../macros/registry.js';
 import { defaultMacroRegistry } from '../macros/index.js';
 import { renderToStorage } from '../markdown/render.js';
+import { parsePlaceholder, placeholder } from '../markdown/placeholder.js';
+import { readInlineSyntax } from '../markdown/inline-syntax.js';
+import { inlineNote } from '../markdown/note.js';
 import { compareStorage } from './canonical.js';
 import { NOTICE_MACRO_ID } from '../publish/notice.js';
 import { rewriteStorageLinks } from './links.js';
@@ -160,6 +163,8 @@ class Converter {
                 return this.listToMd(el);
             if (el.name === 'table') {
                 // tables:'records' — любую таблицу разворачиваем в записи.
+                if (this.hasComplexNote(el.children))
+                    return this.fence(serializeStorage([el]));
                 if (this.tablesAsRecords)
                     return this.recordsTable(el);
                 try {
@@ -352,6 +357,7 @@ class Converter {
         toc: 'toc', children: 'children', jira: 'jira', status: 'status',
         anchor: 'anchor', detailssummary: 'properties-report',
         'portfolio-for-jira-plan': 'portfolio-for-jira-plan',
+        'table-excerpt-include': 'table-excerpt-include',
     };
     tryNativeMd(el, name) {
         const parts = this.macroParts(el);
@@ -363,6 +369,23 @@ class Converter {
         const pmap = new Map(params.map((p) => [p.name, p.value]));
         const oneline = (v) => v !== undefined && !/[\n|{}]/.test(v) && !v.includes('}}');
         let candidate = null;
+        if (['table-filter', 'table-excerpt', 'table-joiner'].includes(name) && richBody !== null) {
+            if (elements(el.children).filter(p => p.name === 'ac:parameter').some(p => elements(p.children).length))
+                return null;
+            if (params.some(p => !/^[\w-]+$/.test(p.name)))
+                return null;
+            const bodyMd = this.bodyMd(richBody);
+            if (bodyMd === null)
+                return null;
+            candidate = `::: ${name}${params.map(p => ` ${p.name}=${JSON.stringify(p.value)}`).join('')}\n${bodyMd}\n:::`;
+            if (this.verifyMacroMarker(el, candidate))
+                return candidate;
+            if (this.verifyTableMacro(el, candidate)) {
+                this.stats.normalized++;
+                return candidate;
+            }
+            return null;
+        }
         if ((name === 'drawio' || name === 'inc-drawio') && richBody === null) {
             const filename = pmap.get('diagramName');
             if (!filename || !oneline(filename) || /[/\\]/.test(filename))
@@ -444,7 +467,11 @@ class Converter {
             const ph = Converter.NATIVE_PLACEHOLDER_NAME[name];
             const attrs = [];
             let head = '';
-            for (const p of params) {
+            const nativeParams = name === 'table-excerpt-include'
+                ? MACRO_EXTRACTORS[name]({ el, paramEls: elements(el.children).filter(p => p.name === 'ac:parameter'), richBody, plainBody })?.params : params;
+            if (!nativeParams)
+                return null;
+            for (const p of nativeParams) {
                 const value = /[|{}\n\r]/.test(p.value) || /^"/.test(p.value) ? JSON.stringify(p.value) : p.value;
                 if (name === 'jira' && p.name === 'key' && head === '') {
                     head = p.value;
@@ -459,7 +486,7 @@ class Converter {
                     continue;
                 }
                 const attrName = name === 'jira' && p.name === 'jqlQuery' ? 'jql' : p.name;
-                if (!/^[A-Za-z-]+$/.test(attrName))
+                if (!/^[A-Za-z_][\w-]*$/.test(attrName))
                     return null;
                 attrs.push(`${attrName}=${value}`);
             }
@@ -728,6 +755,36 @@ class Converter {
             return false;
         }
     }
+    /** Accept editable GFM tables only when the surrounding macros/parameters and normalized cells match. */
+    verifyTableMacro(el, markdown) {
+        const saved = this.readable, stats = { ...this.stats };
+        try {
+            this.readable = true;
+            const render = (md) => processMacros(renderToStorage(md, { images: new Map(), files: new Map() }, { imageStyle: 'attachment', fileStyle: 'attachment', linkify: false }), this.registry).toString();
+            const normalize = (nodes) => nodes.flatMap(node => {
+                if (node.kind !== 'el')
+                    return [node];
+                if (node.name === 'table') {
+                    // Nested block macros require their own faithful conversion; never flatten their semantics.
+                    const hasMacro = (ns) => ns.some(n => n.kind === 'el' && (n.name === 'ac:structured-macro' || hasMacro(n.children)));
+                    if (hasMacro(node.children))
+                        throw new Unrepresentable();
+                    return parseStorage(render(this.readableTable(node)));
+                }
+                return [{ ...node, children: normalize(node.children) }];
+            });
+            return compareStorage(serializeStorage(normalize([el])), serializeStorage(normalize(parseStorage(render(markdown))))).equal;
+        }
+        catch (error) {
+            if (!(error instanceof Unrepresentable))
+                throw error;
+            return false;
+        }
+        finally {
+            this.readable = saved;
+            Object.assign(this.stats, stats);
+        }
+    }
     containsMacroNamed(nodes, name) {
         for (const n of nodes) {
             if (n.kind !== 'el')
@@ -859,6 +916,33 @@ class Converter {
         const row = (cells) => `| ${cells.join(' | ')} |`;
         return [row(header), row(sep), ...bodyRows.map(row)].join('\n');
     }
+    /** Only paragraphs with representable inline content; complex Notes keep storage. */
+    inlineNoteMd(el) {
+        const parts = this.macroParts(el);
+        if (!parts?.richBody || parts.plainBody || parts.params.some(p => !['title', 'icon'].includes(p.name)))
+            return null;
+        const readable = this.readable;
+        this.readable = false;
+        try {
+            const nodes = parts.richBody.children.filter(n => n.kind !== 'text' || n.raw.trim());
+            if (!nodes.length || nodes.some(n => n.kind !== 'el' || n.name !== 'p' || n.attrs.length))
+                return null;
+            const text = nodes.map(n => this.inlineToMd(n.children, { cell: true })).join('\n');
+            const candidate = inlineNote(text, parts.params.map(p => [p.name, p.value]));
+            return this.verifyMacroMarker(el, candidate) ? candidate : null;
+        }
+        catch (e) {
+            if (!(e instanceof Unrepresentable))
+                throw e;
+            return null;
+        }
+        finally {
+            this.readable = readable;
+        }
+    }
+    hasComplexNote(nodes) {
+        return nodes.some(n => n.kind === 'el' && ((n.name === 'ac:structured-macro' && getAttr(n, 'ac:name') === 'note' && this.inlineNoteMd(n) === null) || this.hasComplexNote(n.children)));
+    }
     cellMd(cell) {
         // Единственный <p> внутри ячейки — разворачиваем (типичная форма).
         let content = cell.children;
@@ -867,7 +951,8 @@ class Converter {
             content.every((n) => n.kind !== 'text' || /^[ \t\r\n]*$/.test(n.raw))) {
             content = els[0].children;
         }
-        const md = this.inlineToMd(content, { cell: true }).trim();
+        const hasNote = content.some(n => n.kind === 'el' && n.name === 'ac:structured-macro' && getAttr(n, 'ac:name') === 'note');
+        const md = (hasNote ? content.map(n => n.kind === 'el' && n.name === 'p' && !n.attrs.length ? this.inlineToMd(n.children, { cell: true }) : this.inlineToMd([n], { cell: true })).join('') : this.inlineToMd(content, { cell: true })).trim();
         if (md.includes('\n'))
             throw new Unrepresentable();
         // Пайпы экранируем один раз над всей ячейкой — покрывает и текст, и
@@ -1189,6 +1274,20 @@ class Converter {
                 }
                 return this.readable ? escapeMdText(alt, ctx, true) : this.rawInline(el, ctx);
             }
+            case 'ac:structured-macro': {
+                if (getAttr(el, 'ac:name') === 'note') {
+                    const note = this.inlineNoteMd(el);
+                    if (note !== null)
+                        return note;
+                    throw new Unrepresentable();
+                }
+                const native = this.tryNativeMd(el, getAttr(el, 'ac:name') ?? '');
+                if (native !== null && !native.includes('\n'))
+                    return native;
+                if (this.readable)
+                    return escapeMdText(textContent(el.children), ctx, true);
+                throw new Unrepresentable();
+            }
             case 'ac:image':
                 return this.acImageToMd(el);
             case 'ac:link':
@@ -1237,6 +1336,14 @@ class Converter {
         const href = getAttr(el, 'href') ?? '';
         const inner = this.inlineToMd(el.children, ctx);
         const onlyHref = el.attrs.length === 1 && el.attrs[0][0] === 'href';
+        const children = elements(el.children);
+        if (onlyHref && children.length === 1 && children[0].name === 'ac:image' && el.children.every(n => n.kind !== 'text' || !n.raw.trim())) {
+            const image = readInlineSyntax(this.acImageToMd(children[0]), 0);
+            if (image && ['img', 'structurizr', 'drawio'].includes(image.id)) {
+                const ref = parsePlaceholder(image.body);
+                return placeholder(image.id, ref.name, [...ref.attrs, ['link', href]]);
+            }
+        }
         if ((onlyHref || this.readable) && SAFE_URL_RE.test(href) && !/[[\]]/.test(inner)) {
             return `[${inner}](${href})`; // readable: доп. атрибуты ссылки отбрасываются
         }
@@ -1257,7 +1364,10 @@ class Converter {
                 this.files.add(architecture[1]);
                 this.files.add(architecture[1].replace(/\.dsl$/, '.json'));
                 this.images.add(filename);
-                return `{{structurizr:${architecture[1]}|view=${view}}}`;
+                const attrs = el.attrs.map(([key]) => [key.slice(3), getAttr(el, key) ?? '']);
+                if (el.attrs.some(([key]) => !key.startsWith('ac:')))
+                    throw new Unrepresentable();
+                return placeholder('structurizr', architecture[1], [['view', view], ...attrs.filter(([key, value]) => key !== 'alt' || value !== `Structurizr · ${view}`)]);
             }
         }
         const stem = filename.replace(/\.png$/i, '');
@@ -1268,7 +1378,10 @@ class Converter {
             if (preview && !/[{}|\n/\\]/.test(preview)) {
                 this.files.add(drawioName);
                 this.images.add(preview);
-                return `{{drawio:${drawioName}|format=image${preview !== `${drawioName}.png` ? `|preview=${preview}` : ''}}}`;
+                if (el.attrs.some(([key]) => !key.startsWith('ac:')))
+                    throw new Unrepresentable();
+                const attrs = el.attrs.map(([key]) => [key.slice(3), getAttr(el, key) ?? '']);
+                return placeholder('drawio', drawioName, [['format', 'image'], ...(preview !== `${drawioName}.png` ? [['preview', preview]] : []), ...attrs]);
             }
         }
         // attachments:'local' — картинка как HTML <img> (сохраняет размеры).
@@ -1325,12 +1438,9 @@ class Converter {
                 throw new Unrepresentable();
             attrs.push([k.slice(3), getAttr(el, k) ?? '']);
         }
-        for (const [, v] of attrs)
-            badPlaceholderPart(v);
         badPlaceholderPart(filename);
         this.images.add(filename);
-        const attrStr = attrs.map(([k, v]) => `|${k}=${v}`).join('');
-        return `{{img:${filename}${attrStr}}}`;
+        return placeholder('img', filename, attrs);
     }
     acLinkToMd(el) {
         // readable безотказен: непредставимая ссылка (user-mention, ссылка без цели,
@@ -1366,6 +1476,12 @@ class Converter {
             throw new Unrepresentable();
         }
         const textAttr = text !== undefined ? `|text=${text}` : '';
+        if (ref.name === 'ri:user') {
+            const identity = ref.attrs.find(([key]) => ['ri:userkey', 'ri:username', 'ri:account-id'].includes(key));
+            if (!identity || ref.attrs.length !== 1)
+                throw new Unrepresentable();
+            return placeholder('user', decodeEntities(identity[1]), [['type', identity[0].slice(3)], ...(text === undefined ? [] : [['text', text]])]);
+        }
         if (ref.name === 'ri:page') {
             if (!ref.attrs.every(([k]) => ['ri:content-title', 'ri:space-key', 'ri:version-at-save'].includes(k))) {
                 throw new Unrepresentable();
@@ -1384,6 +1500,13 @@ class Converter {
             }
             const filename = getAttr(ref, 'ri:filename') ?? '';
             this.files.add(filename);
+            if (!this.localFiles && !text && /\.dsl\.([0-9a-f]{2})+\.png$/.test(filename)) {
+                const image = readInlineSyntax(this.acImageToMd({ kind: 'el', name: 'ac:image', attrs: [], children: [ref], selfClosing: false }), 0);
+                if (image?.id === 'structurizr') {
+                    const parsed = parsePlaceholder(image.body);
+                    return placeholder('structurizr', parsed.name, [...parsed.attrs, ['display', 'link']]);
+                }
+            }
             // attachments:'local' — md-ссылка на локальный файл вместо {{file:}}.
             if (this.localFiles) {
                 const label = (text ?? filename).replace(/[[\]]/g, '\\$&');

package/dist/macros/plugins/core.js

@@ -7,6 +7,7 @@
 import { macro } from '../builder.js';
 import { paramMap } from '../types.js';
 import { pageLinkValue, structuredMacro } from '../xml.js';
+import { noteMacro } from './note.js';
 /** Rich-body macro that forwards the listed params (if present). */
 function richBodyMacro(name, allowedParams) {
     return {
@@ -103,7 +104,7 @@ export const coreMacrosPlugin = {
     macros: [
         // Rich-body containers
         richBodyMacro('expand', ['title']),
-        richBodyMacro('note', ['title', 'icon']),
+        noteMacro,
         richBodyMacro('info', ['title', 'icon']),
         richBodyMacro('warning', ['title', 'icon']),
         richBodyMacro('tip', ['title', 'icon']),

package/dist/macros/plugins/drawio.js

@@ -1,6 +1,7 @@
 import { macro } from '../builder.js';
 import { paramMap } from '../types.js';
-import { escapeXmlAttr, structuredMacro } from '../xml.js';
+import { structuredMacro } from '../xml.js';
+import { attachmentImage } from '../../markdown/image.js';
 /** XML keeps its attachment name, including extensionless Confluence diagrams. */
 export const drawioPlugin = {
     name: 'drawio',
@@ -10,7 +11,7 @@ export const drawioPlugin = {
                 if (!name)
                     throw new Error('drawio: diagramName is required');
                 if (params.format === 'image') {
-                    return `<ac:image><ri:attachment ri:filename="${escapeXmlAttr(params.preview || `${name}.png`)}" /></ac:image>`;
+                    return attachmentImage(params.preview || `${name}.png`, ctx.params.filter(p => !['diagramName', 'format', 'preview'].includes(p.name)).map(p => [p.name, p.value]));
                 }
                 if (params.format && params.format !== 'macro')
                     throw new Error('drawio: format must be macro or image');

package/dist/macros/plugins/note.d.ts

@@ -0,0 +1,3 @@
+import type { MacroDefinition } from '../types.js';
+export declare const noteMacro: MacroDefinition;
+export declare function renderInlineNote(body: string, attrs: [string, string][]): string;

package/dist/macros/plugins/note.js

@@ -0,0 +1,13 @@
+import { parseStorage, serializeStorage } from '../../export/xhtml.js';
+import { stableMacroId, structuredMacro } from '../xml.js';
+export const noteMacro = {
+    name: 'note',
+    render: ctx => structuredMacro('note', ctx.macroId, { params: ctx.params.filter(p => ['title', 'icon'].includes(p.name)), richBody: ctx.body }),
+};
+export function renderInlineNote(body, attrs) {
+    body = serializeStorage(parseStorage(body));
+    const params = attrs.map(([name, value]) => ({ name, value })).sort((a, b) => a.name.localeCompare(b.name));
+    if (params.some(p => !['title', 'icon'].includes(p.name)))
+        throw new Error('Inline Note supports title and icon parameters');
+    return noteMacro.render({ macroId: stableMacroId(JSON.stringify([body, params])), params, body });
+}

package/dist/macros/plugins/structurizr.js

@@ -1,6 +1,6 @@
 import { macro } from '../builder.js';
 import { paramMap } from '../types.js';
-import { escapeXmlAttr } from '../xml.js';
+import { attachmentImage } from '../../markdown/image.js';
 export function structurizrPreview(name, view) {
     if (typeof name !== 'string' || !/\.dsl$/i.test(name) || /[/\\{}|]/.test(name) || !view || view.length > 120 || /[{}|\n\r]/.test(view))
         throw new Error('structurizr: a .dsl attachment and view key are required');
@@ -10,8 +10,8 @@ export function structurizrPreview(name, view) {
 export const structurizrPlugin = {
     name: 'structurizr',
     macros: [{ name: 'structurizr', render(ctx) {
-                const { name, view } = paramMap(ctx.params);
-                return `<ac:image ac:alt="${escapeXmlAttr(`Structurizr · ${view}`)}"><ri:attachment ri:filename="${escapeXmlAttr(structurizrPreview(name, view))}" /></ac:image>`;
+                const { name, view, ...attrs } = paramMap(ctx.params);
+                return attachmentImage(structurizrPreview(name, view), Object.entries({ alt: `Structurizr · ${view}`, ...attrs }));
             } }],
 };
 export const structurizr = (name, view) => macro('structurizr').param('name', name).param('view', view).toMarkdown();

package/dist/macros/plugins/table-filter.js

@@ -63,13 +63,7 @@ export const tableFilterPlugin = {
             // Параметры: name — название выборки; hide — скрывать ли содержимое.
             name: 'table-excerpt',
             render: (ctx) => {
-                const map = paramMap(ctx.params);
-                const params = [];
-                if (map.hide === 'true')
-                    params.push({ name: 'hide', value: 'true' });
-                if (map.name)
-                    params.push({ name: 'name', value: map.name });
-                return structuredMacro('table-excerpt', ctx.macroId, { params, richBody: ctx.body });
+                return structuredMacro('table-excerpt', ctx.macroId, { params: ctx.params, richBody: ctx.body });
             },
         },
         {

package/dist/markdown/image.d.ts

@@ -0,0 +1,2 @@
+/** Native attachment images retain Confluence's image toolbar and formatting. */
+export declare function attachmentImage(name: string, attrs: Array<[string, string]>): string;

package/dist/markdown/image.js

@@ -0,0 +1,19 @@
+import { escapeXmlAttr } from '../macros/xml.js';
+/** Native attachment images retain Confluence's image toolbar and formatting. */
+export function attachmentImage(name, attrs) {
+    const values = new Map(attrs);
+    const attachment = `<ri:attachment ri:filename="${escapeXmlAttr(name)}" />`;
+    if (values.get('display') === 'link')
+        return `<ac:link>${attachment}</ac:link>`;
+    const attributes = attrs.filter(([key]) => !['display', 'link'].includes(key));
+    for (const [key] of attributes)
+        if (!/^[A-Za-z_][\w.-]*$/.test(key))
+            throw new Error(`Invalid image attribute: ${key}`);
+    const image = `<ac:image${attributes.map(([key, value]) => ` ac:${key}="${escapeXmlAttr(value)}"`).join('')}>${attachment}</ac:image>`;
+    const link = values.get('link');
+    if (!link)
+        return image;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(link) && !/^(https?|mailto|tel):/i.test(link))
+        throw new Error('Unsupported image link protocol');
+    return `<a href="${escapeXmlAttr(link)}">${image}</a>`;
+}

package/dist/markdown/inline-syntax.d.ts

@@ -0,0 +1,13 @@
+export interface InlineSyntax {
+    id: string;
+    body: string;
+    raw: string;
+    from: number;
+    to: number;
+}
+/** Balanced braces, quoted parameters and escaped delimiters. */
+export declare function readInlineSyntax(source: string, from: number): InlineSyntax | null;
+/** Visit authored macros, excluding fenced and inline code. */
+export declare function replaceInlineSyntax(source: string, replace: (macro: InlineSyntax) => string | undefined): string;
+/** Remove the one GFM escaping layer; keep JSON-encoded backslashes intact. */
+export declare const unescapeTablePipes: (raw: string) => string;

package/dist/markdown/inline-syntax.js

@@ -0,0 +1,72 @@
+/** Balanced braces, quoted parameters and escaped delimiters. */
+export function readInlineSyntax(source, from) {
+    const head = /^\{\{([a-z][a-z0-9-]*)(:|\}\})/.exec(source.slice(from));
+    if (!head)
+        return null;
+    if (head[2] === '}}')
+        return { id: head[1], body: '', raw: head[0], from, to: from + head[0].length };
+    const start = from + head[0].length;
+    let depth = 1, quoted = false;
+    for (let i = start; i < source.length; i++) {
+        if (source[i] === '\\') {
+            i++;
+            continue;
+        }
+        if (source[i] === '"') {
+            quoted = !quoted;
+            continue;
+        }
+        if (quoted)
+            continue;
+        if (source.slice(i, i + 2) === '{{') {
+            depth++;
+            i++;
+        }
+        else if (source.slice(i, i + 2) === '}}') {
+            if (--depth === 0)
+                return { id: head[1], body: source.slice(start, i), raw: source.slice(from, i + 2), from, to: i + 2 };
+            i++;
+        }
+    }
+    return null;
+}
+/** Visit authored macros, excluding fenced and inline code. */
+export function replaceInlineSyntax(source, replace) {
+    let out = '', pos = 0;
+    while (pos < source.length) {
+        if (pos === 0 || source[pos - 1] === '\n') {
+            const fence = /^ {0,3}(`{3,}|~{3,})[^\n]*(?:\n|$)/.exec(source.slice(pos));
+            if (fence) {
+                const end = new RegExp(`^ {0,3}${fence[1][0]}{${fence[1].length},}[ \\t]*(?:\\n|$)`, 'm');
+                const rest = source.slice(pos + fence[0].length), close = end.exec(rest);
+                const to = close ? pos + fence[0].length + close.index + close[0].length : source.length;
+                out += source.slice(pos, to);
+                pos = to;
+                continue;
+            }
+        }
+        if (source[pos] === '\\') {
+            out += source.slice(pos, pos + 2);
+            pos += 2;
+            continue;
+        }
+        if (source[pos] === '`') {
+            const run = /^`+/.exec(source.slice(pos))[0], end = source.indexOf(run, pos + run.length);
+            if (end >= 0) {
+                out += source.slice(pos, end + run.length);
+                pos = end + run.length;
+                continue;
+            }
+        }
+        const macro = source.slice(pos, pos + 2) === '{{' ? readInlineSyntax(source, pos) : null;
+        if (macro) {
+            out += replace(macro) ?? macro.raw;
+            pos = macro.to;
+            continue;
+        }
+        out += source[pos++];
+    }
+    return out;
+}
+/** Remove the one GFM escaping layer; keep JSON-encoded backslashes intact. */
+export const unescapeTablePipes = (raw) => raw.replace(/(\\+)\|/g, (_match, slash) => (slash.length % 2 ? slash.slice(1) : slash) + '|');

package/dist/markdown/native.js

@@ -30,6 +30,7 @@
  * Внутри fenced-код-блоков (``` / ~~~) синтаксис не интерпретируется.
  */
 import { escapeParamValue } from '../macros/builder.js';
+import { replaceInlineSyntax } from './inline-syntax.js';
 /** Панели: тег admonition → имя макроса. */
 export const NATIVE_ADMONITIONS = {
     INFO: 'info',
@@ -42,6 +43,9 @@ export const NATIVE_DIRECTIVES = {
     properties: 'details',
     expand: 'expand',
     panel: 'panel',
+    'table-filter': 'table-filter',
+    'table-excerpt': 'table-excerpt',
+    'table-joiner': 'table-joiner',
 };
 /** Строчные плейсхолдеры: имя → имя макроса. */
 export const NATIVE_PLACEHOLDERS = {
@@ -55,6 +59,7 @@ export const NATIVE_PLACEHOLDERS = {
     anchor: 'anchor',
     'properties-report': 'detailssummary',
     'portfolio-for-jira-plan': 'portfolio-for-jira-plan',
+    'table-excerpt-include': 'table-excerpt-include',
 };
 /** Полный перечень макросов с нативной md-разметкой (для документации/UI). */
 export function nativeMacroList() {
@@ -63,12 +68,14 @@ export function nativeMacroList() {
         { macro: 'structurizr', syntax: '{{structurizr:workspace.dsl|view=containers}}' },
         { macro: 'drawio', syntax: '{{drawio:diagram.drawio|format=macro}} | {{drawio:diagram.drawio|format=image}}' },
         { macro: 'info', syntax: '> [!INFO] Заголовок?' },
-        { macro: 'note', syntax: '> [!NOTE] Заголовок?' },
+        { macro: 'note', syntax: '> [!NOTE] Заголовок? | {{note:Текст}}' },
         { macro: 'warning', syntax: '> [!WARNING] Заголовок?' },
         { macro: 'tip', syntax: '> [!TIP] Заголовок?' },
         { macro: 'details', syntax: '::: properties [id=…] [hidden=true] … :::' },
         { macro: 'expand', syntax: '::: expand Заголовок … :::' },
         { macro: 'panel', syntax: '::: panel title=… … :::' },
+        ...['table-filter', 'table-excerpt', 'table-joiner'].map(macro => ({ macro, syntax: `::: ${macro} name="…" … :::` })),
+        { macro: 'table-excerpt-include', syntax: '{{table-excerpt-include:name=…|page=…|space=…}}' },
         { macro: 'toc', syntax: '{{toc}} | {{toc:maxLevel=3}}' },
         { macro: 'children', syntax: '{{children}} | {{children:depth=2}}' },
         { macro: 'jira', syntax: '{{jira:KEY-1}} | {{jira:jql=…|maximumIssues=20}}' },
@@ -81,7 +88,6 @@ export function nativeMacroList() {
 const ADMONITION_FIRST_RE = /^>\s*\[!([A-Za-z]+)\]\s*(.*)$/;
 const DIRECTIVE_OPEN_RE = /^:::\s+([a-z-]+)(?:\s+(.*?))?\s*$/;
 const DIRECTIVE_CLOSE_RE = /^:::\s*$/;
-const PLACEHOLDER_INLINE_RE = /\{\{(search|drawio|structurizr|toc|children|jira|status|anchor|properties-report|portfolio-for-jira-plan)(?::((?:"(?:\\.|[^"\\])*"|[^{}"]|\{[^{])*?))?\}\}/g;
 const FENCE_RE = /^\s*(`{3,}|~{3,})/;
 /** Компактная пара маркеров без тела — для строчного контекста. */
 function inlineMarker(macroName, params) {
@@ -174,7 +180,7 @@ function placeholderParams(kind, raw) {
     return params;
 }
 function replaceInline(line) {
-    return line.replace(PLACEHOLDER_INLINE_RE, (_full, kind, raw) => inlineMarker(NATIVE_PLACEHOLDERS[kind], placeholderParams(kind, raw)));
+    return replaceInlineSyntax(line, ref => ref.id in NATIVE_PLACEHOLDERS ? inlineMarker(NATIVE_PLACEHOLDERS[ref.id], placeholderParams(ref.id, ref.body)) : undefined);
 }
 /** Параметры директивы: токены `k=v` (значение можно в кавычках) + свободный текст → title. */
 function directiveParams(name, rest) {

package/dist/markdown/note-layout.d.ts

@@ -0,0 +1 @@
+export declare function liftInlineNotes(html: string): string;

package/dist/markdown/note-layout.js

@@ -0,0 +1,41 @@
+import { getAttr, parseStorage, serializeStorage } from '../export/xhtml.js';
+const isNote = (n) => n.kind === 'el' && n.name === 'ac:structured-macro' && getAttr(n, 'ac:name') === 'note';
+/** Split inline wrappers as well, so a Note never becomes a block inside <p>/<strong>. */
+function split(nodes) {
+    const result = [[]];
+    for (const n of nodes) {
+        if (isNote(n)) {
+            result.push([n], []);
+            continue;
+        }
+        if (n.kind !== 'el') {
+            result[result.length - 1].push(n);
+            continue;
+        }
+        const inner = split(n.children);
+        for (const chunk of inner) {
+            if (chunk.length === 1 && isNote(chunk[0]))
+                result.push(chunk, []);
+            else if (chunk.length)
+                result[result.length - 1].push({ ...n, children: chunk });
+        }
+        if (!n.children.length)
+            result[result.length - 1].push(n);
+    }
+    return result.filter(chunk => chunk.length);
+}
+export function liftInlineNotes(html) {
+    const walk = (nodes) => nodes.flatMap(n => {
+        if (n.kind !== 'el')
+            return [n];
+        const children = walk(n.children);
+        if (['td', 'th'].includes(n.name) && children.some(isNote)) {
+            const blocks = split(children).flatMap(chunk => chunk.every(n => isNote(n) || (n.kind === 'el' && n.name === 'p')) ? chunk : [{ kind: 'el', name: 'p', attrs: [], children: chunk, selfClosing: false }]);
+            return [{ ...n, children: blocks }];
+        }
+        if (n.name !== 'p')
+            return [{ ...n, children }];
+        return split(children).map(chunk => chunk.length === 1 && isNote(chunk[0]) ? chunk[0] : { ...n, children: chunk });
+    });
+    return serializeStorage(walk(parseStorage(html)));
+}

package/dist/markdown/note.d.ts

@@ -0,0 +1,6 @@
+/** Plain body is Markdown; quoted body permits parameters and a single-line table cell. */
+export declare function parseInlineNote(body: string): {
+    text: string;
+    attrs: [string, string][];
+};
+export declare function inlineNote(text: string, attrs?: [string, string][]): string;

package/dist/markdown/note.js

@@ -0,0 +1,26 @@
+import { parsePlaceholder, quotePlaceholder } from './placeholder.js';
+/** Plain body is Markdown; quoted body permits parameters and a single-line table cell. */
+export function parseInlineNote(body) {
+    if (body.startsWith('"')) {
+        const ref = parsePlaceholder(body);
+        return { text: ref.name, attrs: ref.attrs };
+    }
+    let text = '';
+    for (let i = 0; i < body.length; i++) {
+        if (body[i] === '\\' && body[i + 1] === 'n') {
+            text += '\n';
+            i++;
+        }
+        else if (body[i] === '\\' && body[i + 1] === '\\') {
+            text += '\\\\';
+            i++;
+        }
+        else
+            text += body[i];
+    }
+    return { text, attrs: [] };
+}
+export function inlineNote(text, attrs = []) {
+    // JSON quotes avoid confusing nested macro pipes with Note parameters.
+    return `{{note:${JSON.stringify(text)}${attrs.map(([key, value]) => `|${key}=${quotePlaceholder(value)}`).join('')}}}`;
+}

package/dist/markdown/placeholder.d.ts

@@ -0,0 +1,8 @@
+export interface PlaceholderRef {
+    name: string;
+    attrs: Array<[string, string]>;
+}
+export declare const PLACEHOLDER_RE: RegExp;
+export declare const quotePlaceholder: (value: string) => string;
+export declare function parsePlaceholder(body: string): PlaceholderRef;
+export declare function placeholder(kind: string, name: string, attrs?: Array<[string, string]>): string;

package/dist/markdown/placeholder.js

@@ -0,0 +1,23 @@
+export const PLACEHOLDER_RE = /\{\{(img|file|page):((?:"(?:\\.|[^"\\])*"|[^{}"]|\{[^{])*?)\}\}/g;
+const unquote = (value) => {
+    if (value.startsWith('"') && value.endsWith('"')) {
+        try {
+            return JSON.parse(value);
+        }
+        catch { /* Legacy values remain literal. */ }
+    }
+    return value;
+};
+export const quotePlaceholder = (value) => /[|{}"\\\r\n]/.test(value) ? JSON.stringify(value) : value;
+export function parsePlaceholder(body) {
+    const parts = body.match(/(?:"(?:\\.|[^"\\])*"|[^|"])+/g) ?? [];
+    const name = unquote((parts.shift() ?? '').trim());
+    const attrs = parts.map(part => {
+        const eq = part.indexOf('=');
+        return eq < 0 ? [part.trim(), ''] : [part.slice(0, eq).trim(), unquote(part.slice(eq + 1).trim())];
+    });
+    return { name, attrs };
+}
+export function placeholder(kind, name, attrs = []) {
+    return `{{${kind}:${quotePlaceholder(name)}${attrs.map(([key, value]) => `|${key}=${quotePlaceholder(value)}`).join('')}}}`;
+}

package/dist/markdown/render.d.ts

@@ -1,18 +1,10 @@
+export { PLACEHOLDER_RE, parsePlaceholder, type PlaceholderRef } from './placeholder.js';
 /**
  * Плейсхолдеры: `{{img:name}}`, `{{file:name}}`, `{{page:Title}}`.
  * После имени допустимы `|key=value`-атрибуты:
  *   {{img:chart.png|thumbnail=true|height=250}}
  *   {{page:Другая страница|space=DOCS|text=якорный текст}}
  */
-export declare const PLACEHOLDER_RE: RegExp;
-export interface PlaceholderRef {
-    /** Имя файла (img/file) или title страницы (page). */
-    name: string;
-    /** `|key=value`-атрибуты в порядке записи. */
-    attrs: Array<[string, string]>;
-}
-/** Разбирает содержимое плейсхолдера: `name|k=v|k2=v2`. */
-export declare function parsePlaceholder(body: string): PlaceholderRef;
 export interface ExtractedPlaceholders {
     images: string[];
     files: string[];
@@ -67,24 +59,5 @@ export interface RenderStorageOptions {
 export declare class MissingAttachmentUrlError extends Error {
     constructor(message: string);
 }
-/**
- * Превращает Markdown в Confluence storage format.
- *
- * Логика двушаговая:
- *   1) markdown-it рендерит сам Markdown (без знания про плейсхолдеры).
- *      `{{img:foo}}` и `{{file:foo}}` для markdown-it — обычный текст
- *      без спецсимволов, доходят до выхода нетронутыми (могут быть
- *      обёрнуты в <p>...</p>, что нас устраивает).
- *   2) В готовом HTML регуляркой подставляем `<img src=URL/>` и
- *      `<a href=URL>filename</a>` на места плейсхолдеров. URL обязан
- *      существовать для каждого плейсхолдера — иначе
- *      MissingAttachmentUrlError.
- *
- * Раньше использовалась схема через sentinel-токены (` CFLIMG_0 `):
- * markdown-it трогал окружающие пробелы при упаковке в <p>, sentinel
- * терял пробелы, итоговый .split() не находил совпадения и в Confluence
- * вместо картинки попадал кусок «CFLIMG_0». Прямая регекс-замена по
- * HTML этой проблемы лишена — `{{img:foo}}` мимо markdown-it проходит
- * посимвольно.
- */
+/** Render Markdown after shielding authored macros from GFM table/inline parsing. */
 export declare function renderToStorage(markdown: string, urls: AttachmentUrls, opts?: RenderStorageOptions): string;

package/dist/markdown/render.js

@@ -1,5 +1,12 @@
 import MarkdownIt from 'markdown-it';
-import { nativeToMarkers } from './native.js';
+import { nativeToMarkers, NATIVE_PLACEHOLDERS } from './native.js';
+import { parsePlaceholder, placeholder } from './placeholder.js';
+import { attachmentImage } from './image.js';
+import { replaceInlineSyntax, unescapeTablePipes } from './inline-syntax.js';
+import { parseInlineNote } from './note.js';
+import { renderInlineNote } from '../macros/plugins/note.js';
+import { liftInlineNotes } from './note-layout.js';
+export { PLACEHOLDER_RE, parsePlaceholder } from './placeholder.js';
 // xhtmlOut: true — Confluence storage format = XHTML, void-элементы
 // (<hr/>, <br/>, <img/>) обязаны быть самозакрывающимися.
 // html: true — разрешить HTML (нужно для <!-- MACRO:... --> комментариев)
@@ -15,40 +22,20 @@ const md = new MarkdownIt(mdOptions);
 // для страниц из exportPage — иначе round-trip превращал бы нессылочные
 // упоминания URL в <a>.
 const mdNoLinkify = new MarkdownIt({ ...mdOptions, linkify: false });
-/**
- * Плейсхолдеры: `{{img:name}}`, `{{file:name}}`, `{{page:Title}}`.
- * После имени допустимы `|key=value`-атрибуты:
- *   {{img:chart.png|thumbnail=true|height=250}}
- *   {{page:Другая страница|space=DOCS|text=якорный текст}}
- */
-export const PLACEHOLDER_RE = /\{\{(img|file|page):([^}]+)\}\}/g;
-/** Разбирает содержимое плейсхолдера: `name|k=v|k2=v2`. */
-export function parsePlaceholder(body) {
-    const parts = body.split('|');
-    const name = parts[0].trim();
-    const attrs = [];
-    for (const part of parts.slice(1)) {
-        const eq = part.indexOf('=');
-        if (eq === -1)
-            attrs.push([part.trim(), '']);
-        else
-            attrs.push([part.slice(0, eq).trim(), part.slice(eq + 1).trim()]);
-    }
-    return { name, attrs };
-}
 export function extractPlaceholders(markdown) {
     const images = new Set();
     const files = new Set();
     const pages = new Set();
-    for (const m of markdown.matchAll(PLACEHOLDER_RE)) {
-        const { name } = parsePlaceholder(m[2]);
-        if (m[1] === 'img')
-            images.add(name);
-        else if (m[1] === 'file')
-            files.add(name);
-        else
-            pages.add(name);
-    }
+    const collect = (source) => replaceInlineSyntax(source, ref => {
+        if (ref.id === 'note')
+            collect(parseInlineNote(ref.body).text);
+        else if (['img', 'file', 'page'].includes(ref.id)) {
+            const { name } = parsePlaceholder(ref.body);
+            (ref.id === 'img' ? images : ref.id === 'file' ? files : pages).add(name);
+        }
+        return undefined;
+    });
+    collect(markdown);
     return { images: [...images], files: [...files], pages: [...pages] };
 }
 function escapeXmlAttr(s) {
@@ -71,13 +58,15 @@ function escapeXmlAttr(s) {
 export function renameImagePlaceholders(markdown, renames) {
     if (renames.size === 0)
         return markdown;
-    return markdown.replace(/\{\{img:([^}]+)\}\}/g, (full, rawBody) => {
-        const { name, attrs } = parsePlaceholder(rawBody);
+    return replaceInlineSyntax(markdown, ref => {
+        if (ref.id !== 'img')
+            return;
+        const full = ref.raw;
+        const { name, attrs } = parsePlaceholder(ref.body);
         const renamed = renames.get(name);
         if (!renamed)
             return full;
-        const attrStr = attrs.map(([k, v]) => `|${k}=${v}`).join('');
-        return `{{img:${renamed}${attrStr}}}`;
+        return placeholder('img', renamed, attrs);
     });
 }
 export class MissingAttachmentUrlError extends Error {
@@ -86,32 +75,68 @@ export class MissingAttachmentUrlError extends Error {
         this.name = 'MissingAttachmentUrlError';
     }
 }
-/**
- * Превращает Markdown в Confluence storage format.
- *
- * Логика двушаговая:
- *   1) markdown-it рендерит сам Markdown (без знания про плейсхолдеры).
- *      `{{img:foo}}` и `{{file:foo}}` для markdown-it — обычный текст
- *      без спецсимволов, доходят до выхода нетронутыми (могут быть
- *      обёрнуты в <p>...</p>, что нас устраивает).
- *   2) В готовом HTML регуляркой подставляем `<img src=URL/>` и
- *      `<a href=URL>filename</a>` на места плейсхолдеров. URL обязан
- *      существовать для каждого плейсхолдера — иначе
- *      MissingAttachmentUrlError.
- *
- * Раньше использовалась схема через sentinel-токены (` CFLIMG_0 `):
- * markdown-it трогал окружающие пробелы при упаковке в <p>, sentinel
- * терял пробелы, итоговый .split() не находил совпадения и в Confluence
- * вместо картинки попадал кусок «CFLIMG_0». Прямая регекс-замена по
- * HTML этой проблемы лишена — `{{img:foo}}` мимо markdown-it проходит
- * посимвольно.
- */
+/** Render Markdown after shielding authored macros from GFM table/inline parsing. */
 export function renderToStorage(markdown, urls, opts = {}) {
     // Нативный md-синтаксис макросов (панели, ::: properties, {{toc}} …) —
     // сахар над маркерами: переписываем до markdown-it (см. native.ts).
+    const placeholders = [];
+    let prefix = 'CFLATTACHTOKEN';
+    while (markdown.includes(prefix))
+        prefix += 'X';
+    markdown = replaceInlineSyntax(markdown, ref => {
+        if (!['img', 'file', 'page', 'user', 'note'].includes(ref.id) && !(ref.id in NATIVE_PLACEHOLDERS))
+            return;
+        const line = markdown.slice(markdown.lastIndexOf('\n', ref.from - 1) + 1, ref.from);
+        const cell = line.trimStart().startsWith('|');
+        placeholders.push(cell ? { ...ref, raw: unescapeTablePipes(ref.raw), body: unescapeTablePipes(ref.body) } : ref);
+        return `${prefix}${placeholders.length - 1}TOKEN`;
+    });
     markdown = nativeToMarkers(markdown);
     const renderer = opts.linkify === false ? mdNoLinkify : md;
     let html = renderer.render(markdown);
+    const renderPlaceholder = (kind, body) => {
+        const { name, attrs } = parsePlaceholder(body);
+        if (kind === 'user') {
+            const map = Object.fromEntries(attrs), type = map.type || 'userkey';
+            if (!['userkey', 'username', 'account-id'].includes(type))
+                throw new Error('Unknown Confluence user identity type');
+            const body = map.text === undefined ? '' : `<ac:plain-text-link-body><![CDATA[${map.text.replace(/]]>/g, ']]]]><![CDATA[>')}]]></ac:plain-text-link-body>`;
+            return `<ac:link><ri:user ri:${type}="${escapeXmlAttr(name)}" />${body}</ac:link>`;
+        }
+        if (kind === 'page') {
+            return renderPageLink(name, attrs);
+        }
+        if (kind === 'img') {
+            if (opts.imageStyle === 'attachment') {
+                return attachmentImage(name, attrs);
+            }
+            const url = urls.images.get(name);
+            if (!url) {
+                throw new MissingAttachmentUrlError(`No uploaded URL for image '${name}' — was it included in publishPage().images and successfully uploaded?`);
+            }
+            return `<img src="${escapeXmlAttr(url)}" alt="${escapeXmlAttr(name)}" />`;
+        }
+        if (opts.fileStyle === 'attachment') {
+            const text = attrs.find(([k]) => k === 'text')?.[1];
+            const body = text !== undefined ? plainTextLinkBody(text) : '';
+            return `<ac:link><ri:attachment ri:filename="${escapeXmlAttr(name)}" />${body}</ac:link>`;
+        }
+        const url = urls.files.get(name);
+        if (!url) {
+            throw new MissingAttachmentUrlError(`No uploaded URL for file '${name}' — was it included in publishPage().files and successfully uploaded?`);
+        }
+        return `<a href="${escapeXmlAttr(url)}">${escapeXmlAttr(name)}</a>`;
+    };
+    html = html.replace(new RegExp(prefix + '(\\d+)TOKEN', 'g'), (_full, index) => {
+        const ref = placeholders[Number(index)];
+        if (ref.id === 'note') {
+            const note = parseInlineNote(ref.body);
+            const body = renderToStorage(note.text.replace(/\r?\n/g, '\n\n'), urls, opts);
+            return renderInlineNote(body.trim(), note.attrs);
+        }
+        return ['img', 'file', 'page', 'user'].includes(ref.id) ? renderPlaceholder(ref.id, ref.body) : nativeToMarkers(ref.raw);
+    });
+    html = html.replace(/<p>((?:\s*<!-- MACRO:start:[^>]* -->\s*<!-- MACRO:end:[^>]* -->\s*)+)<\/p>/g, '$1');
     // ```confluence-storage — транспорт для дословного XHTML (ac:/ri:-теги
     // markdown-it сквозь себя не пропускает). Fence рендерится в экранированный
     // <pre><code>; здесь разэкранируем содержимое обратно в живую разметку.
@@ -160,35 +185,7 @@ export function renderToStorage(markdown, urls, opts = {}) {
             return `<ac:link><ri:attachment ri:filename="${escapeXmlAttr(resource.attachment)}" />${body}</ac:link>`;
         });
     }
-    return html.replace(PLACEHOLDER_RE, (_full, kind, rawBody) => {
-        const { name, attrs } = parsePlaceholder(String(rawBody));
-        if (kind === 'page') {
-            return renderPageLink(name, attrs);
-        }
-        if (kind === 'img') {
-            if (opts.imageStyle === 'attachment') {
-                const acAttrs = attrs
-                    .map(([k, v]) => ` ac:${k}="${escapeXmlAttr(v)}"`)
-                    .join('');
-                return `<ac:image${acAttrs}><ri:attachment ri:filename="${escapeXmlAttr(name)}" /></ac:image>`;
-            }
-            const url = urls.images.get(name);
-            if (!url) {
-                throw new MissingAttachmentUrlError(`No uploaded URL for image '${name}' — was it included in publishPage().images and successfully uploaded?`);
-            }
-            return `<img src="${escapeXmlAttr(url)}" alt="${escapeXmlAttr(name)}" />`;
-        }
-        if (opts.fileStyle === 'attachment') {
-            const text = attrs.find(([k]) => k === 'text')?.[1];
-            const body = text !== undefined ? plainTextLinkBody(text) : '';
-            return `<ac:link><ri:attachment ri:filename="${escapeXmlAttr(name)}" />${body}</ac:link>`;
-        }
-        const url = urls.files.get(name);
-        if (!url) {
-            throw new MissingAttachmentUrlError(`No uploaded URL for file '${name}' — was it included in publishPage().files and successfully uploaded?`);
-        }
-        return `<a href="${escapeXmlAttr(url)}">${escapeXmlAttr(name)}</a>`;
-    });
+    return placeholders.some(ref => ref.id === 'note') ? liftInlineNotes(html) : html;
 }
 function renderPageLink(title, attrs) {
     const space = attrs.find(([k]) => k === 'space')?.[1];

package/dist/syntax.d.ts

@@ -0,0 +1,3 @@
+export { PLACEHOLDER_RE, parsePlaceholder, placeholder, quotePlaceholder, type PlaceholderRef } from './markdown/placeholder.js';
+export { readInlineSyntax, replaceInlineSyntax, unescapeTablePipes, type InlineSyntax } from './markdown/inline-syntax.js';
+export { parseInlineNote, inlineNote } from './markdown/note.js';

package/dist/syntax.js

@@ -0,0 +1,4 @@
+// Browser-safe authoring helpers shared with editors.
+export { PLACEHOLDER_RE, parsePlaceholder, placeholder, quotePlaceholder } from './markdown/placeholder.js';
+export { readInlineSyntax, replaceInlineSyntax, unescapeTablePipes } from './markdown/inline-syntax.js';
+export { parseInlineNote, inlineNote } from './markdown/note.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-md-sync",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Publish Markdown to Confluence (Data Center & Cloud): idempotent page sync, attachment dedup, tables and a pluggable macro system",
   "keywords": [
     "confluence",
@@ -40,6 +40,10 @@
     "./macros": {
       "types": "./dist/macros/index.d.ts",
       "import": "./dist/macros/index.js"
+    },
+    "./syntax": {
+      "types": "./dist/syntax.d.ts",
+      "import": "./dist/syntax.js"
     }
   },
   "bin": {