confluence-md-sync 0.2.0 → 0.3.0

package/dist/export/xhtml.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Мини-парсер и сериализатор storage-формата Confluence.
+ *
+ * Storage — well-formed XML-фрагмент (XHTML + пространства имён ac:/ri:),
+ * но с HTML-сущностями (  и т.п.), которые «настоящий» XML-парсер не
+ * переварит. Поэтому свой парсер: сущности в тексте и атрибутах НЕ
+ * декодируются (хранятся как в исходнике — это даёт побайтовую
+ * сериализацию обратно), а декодирование по требованию делает
+ * {@link decodeEntities}.
+ */
+export interface XElement {
+    kind: 'el';
+    name: string;
+    /** Пары [имя, raw-значение] в исходном порядке; значения не декодированы. */
+    attrs: Array<[string, string]>;
+    children: XNode[];
+    selfClosing: boolean;
+}
+export interface XText {
+    kind: 'text';
+    /** Текст как в исходнике, сущности не декодированы. */
+    raw: string;
+}
+export interface XCdata {
+    kind: 'cdata';
+    text: string;
+}
+export interface XComment {
+    kind: 'comment';
+    text: string;
+}
+export type XNode = XElement | XText | XCdata | XComment;
+export declare class StorageParseError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/** Парсит storage-фрагмент в список узлов. Бросает StorageParseError. */
+export declare function parseStorage(input: string): XNode[];
+/** Сериализует узлы обратно в storage. Для нетронутого дерева — побайтово. */
+export declare function serializeStorage(nodes: XNode[]): string;
+/** Декодирует HTML/XML-сущности (именованные из словаря + числовые). */
+export declare function decodeEntities(raw: string): string;
+/** Значение атрибута элемента (декодированное) или undefined. */
+export declare function getAttr(el: XElement, name: string): string | undefined;
+/** Текстовое содержимое поддерева (сущности декодированы, теги отброшены). */
+export declare function textContent(nodes: XNode[]): string;
+/** true, если в поддереве есть элементы с namespace-префиксом (ac:, ri:, …). */
+export declare function hasNamespacedElements(nodes: XNode[]): boolean;
+/** Только элементы среди узлов. */
+export declare function elements(nodes: XNode[]): XElement[];
+/** Экранирует текст для XML (используется при генерации новых узлов). */
+export declare function escapeXmlText(s: string): string;

package/dist/export/xhtml.js

@@ -0,0 +1,230 @@
+/**
+ * Мини-парсер и сериализатор storage-формата Confluence.
+ *
+ * Storage — well-formed XML-фрагмент (XHTML + пространства имён ac:/ri:),
+ * но с HTML-сущностями (  и т.п.), которые «настоящий» XML-парсер не
+ * переварит. Поэтому свой парсер: сущности в тексте и атрибутах НЕ
+ * декодируются (хранятся как в исходнике — это даёт побайтовую
+ * сериализацию обратно), а декодирование по требованию делает
+ * {@link decodeEntities}.
+ */
+export class StorageParseError extends Error {
+    position;
+    constructor(message, position) {
+        super(`${message} (at offset ${position})`);
+        this.position = position;
+        this.name = 'StorageParseError';
+    }
+}
+// XHTML-«пустые» элементы: на случай невалидного <br> без самозакрытия.
+const VOID_ELEMENTS = new Set(['br', 'hr', 'img', 'col', 'input', 'meta', 'link']);
+const NAME_RE = /[A-Za-z_][A-Za-z0-9._:-]*/y;
+/** Парсит storage-фрагмент в список узлов. Бросает StorageParseError. */
+export function parseStorage(input) {
+    const root = [];
+    const stack = [];
+    let current = root;
+    let i = 0;
+    const pushText = (from, to) => {
+        if (to > from)
+            current.push({ kind: 'text', raw: input.slice(from, to) });
+    };
+    let textStart = 0;
+    while (i < input.length) {
+        const lt = input.indexOf('<', i);
+        if (lt === -1)
+            break;
+        pushText(textStart, lt);
+        if (input.startsWith('<![CDATA[', lt)) {
+            const end = input.indexOf(']]>', lt + 9);
+            if (end === -1)
+                throw new StorageParseError('unterminated CDATA', lt);
+            current.push({ kind: 'cdata', text: input.slice(lt + 9, end) });
+            i = textStart = end + 3;
+            continue;
+        }
+        if (input.startsWith('<!--', lt)) {
+            const end = input.indexOf('-->', lt + 4);
+            if (end === -1)
+                throw new StorageParseError('unterminated comment', lt);
+            current.push({ kind: 'comment', text: input.slice(lt + 4, end) });
+            i = textStart = end + 3;
+            continue;
+        }
+        if (input.startsWith('</', lt)) {
+            NAME_RE.lastIndex = lt + 2;
+            const m = NAME_RE.exec(input);
+            if (!m)
+                throw new StorageParseError('malformed closing tag', lt);
+            const gt = input.indexOf('>', lt);
+            if (gt === -1)
+                throw new StorageParseError('unterminated closing tag', lt);
+            const frame = stack.pop();
+            if (!frame || frame.el.name !== m[0]) {
+                throw new StorageParseError(`unexpected </${m[0]}>${frame ? `, open element is <${frame.el.name}>` : ''}`, lt);
+            }
+            current = stack.length > 0 ? stack[stack.length - 1].children : root;
+            i = textStart = gt + 1;
+            continue;
+        }
+        // Открывающий тег
+        NAME_RE.lastIndex = lt + 1;
+        const nameMatch = NAME_RE.exec(input);
+        if (!nameMatch) {
+            // Не тег (например, одинокий '<' — в валидном storage не бывает).
+            throw new StorageParseError('malformed tag', lt);
+        }
+        const el = {
+            kind: 'el',
+            name: nameMatch[0],
+            attrs: [],
+            children: [],
+            selfClosing: false,
+        };
+        i = NAME_RE.lastIndex;
+        // Атрибуты
+        for (;;) {
+            while (/[\s]/.test(input[i] ?? ''))
+                i++;
+            const ch = input[i];
+            if (ch === '>') {
+                i++;
+                break;
+            }
+            if (ch === '/') {
+                if (input[i + 1] !== '>')
+                    throw new StorageParseError('malformed self-closing tag', i);
+                el.selfClosing = true;
+                i += 2;
+                break;
+            }
+            NAME_RE.lastIndex = i;
+            const attrName = NAME_RE.exec(input);
+            if (!attrName)
+                throw new StorageParseError(`malformed attribute in <${el.name}>`, i);
+            i = NAME_RE.lastIndex;
+            while (/\s/.test(input[i] ?? ''))
+                i++;
+            if (input[i] !== '=') {
+                // Булев атрибут без значения — в storage не встречается, но переживём.
+                el.attrs.push([attrName[0], '']);
+                continue;
+            }
+            i++;
+            while (/\s/.test(input[i] ?? ''))
+                i++;
+            const quote = input[i];
+            if (quote !== '"' && quote !== "'") {
+                throw new StorageParseError(`unquoted attribute value in <${el.name}>`, i);
+            }
+            const endQuote = input.indexOf(quote, i + 1);
+            if (endQuote === -1)
+                throw new StorageParseError('unterminated attribute value', i);
+            el.attrs.push([attrName[0], input.slice(i + 1, endQuote)]);
+            i = endQuote + 1;
+        }
+        current.push(el);
+        if (!el.selfClosing && !VOID_ELEMENTS.has(el.name.toLowerCase())) {
+            stack.push({ el, children: el.children });
+            current = el.children;
+        }
+        else if (!el.selfClosing) {
+            el.selfClosing = true; // нормализуем невалидный <br> к <br/>
+        }
+        textStart = i;
+    }
+    pushText(textStart, input.length);
+    if (stack.length > 0) {
+        throw new StorageParseError(`unclosed element <${stack[stack.length - 1].el.name}>`, input.length);
+    }
+    return root;
+}
+/** Сериализует узлы обратно в storage. Для нетронутого дерева — побайтово. */
+export function serializeStorage(nodes) {
+    let out = '';
+    for (const n of nodes) {
+        switch (n.kind) {
+            case 'text':
+                out += n.raw;
+                break;
+            case 'cdata':
+                out += `<![CDATA[${n.text}]]>`;
+                break;
+            case 'comment':
+                out += `<!--${n.text}-->`;
+                break;
+            case 'el': {
+                const attrs = n.attrs.map(([k, v]) => ` ${k}="${v}"`).join('');
+                if (n.selfClosing) {
+                    out += `<${n.name}${attrs} />`;
+                }
+                else {
+                    out += `<${n.name}${attrs}>${serializeStorage(n.children)}</${n.name}>`;
+                }
+                break;
+            }
+        }
+    }
+    return out;
+}
+// Частые именованные сущности Confluence-страниц; остальное — числовые.
+const NAMED_ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'",
+    nbsp: ' ', shy: '­',
+    rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”',
+    ndash: '–', mdash: '—', hellip: '…',
+    laquo: '«', raquo: '»', times: '×', middot: '·',
+    deg: '°', plusmn: '±', copy: '©', reg: '®', trade: '™',
+    bull: '•', rarr: '→', larr: '←', darr: '↓', uarr: '↑',
+    sect: '§', para: '¶', euro: '€',
+};
+/** Декодирует HTML/XML-сущности (именованные из словаря + числовые). */
+export function decodeEntities(raw) {
+    return raw.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (full, body) => {
+        if (body.startsWith('#x') || body.startsWith('#X')) {
+            return String.fromCodePoint(parseInt(body.slice(2), 16));
+        }
+        if (body.startsWith('#')) {
+            return String.fromCodePoint(parseInt(body.slice(1), 10));
+        }
+        return NAMED_ENTITIES[body] ?? full;
+    });
+}
+/** Значение атрибута элемента (декодированное) или undefined. */
+export function getAttr(el, name) {
+    const found = el.attrs.find(([k]) => k === name);
+    return found === undefined ? undefined : decodeEntities(found[1]);
+}
+/** Текстовое содержимое поддерева (сущности декодированы, теги отброшены). */
+export function textContent(nodes) {
+    let out = '';
+    for (const n of nodes) {
+        if (n.kind === 'text')
+            out += decodeEntities(n.raw);
+        else if (n.kind === 'cdata')
+            out += n.text;
+        else if (n.kind === 'el')
+            out += textContent(n.children);
+    }
+    return out;
+}
+/** true, если в поддереве есть элементы с namespace-префиксом (ac:, ri:, …). */
+export function hasNamespacedElements(nodes) {
+    for (const n of nodes) {
+        if (n.kind === 'el') {
+            if (n.name.includes(':'))
+                return true;
+            if (hasNamespacedElements(n.children))
+                return true;
+        }
+    }
+    return false;
+}
+/** Только элементы среди узлов. */
+export function elements(nodes) {
+    return nodes.filter((n) => n.kind === 'el');
+}
+/** Экранирует текст для XML (используется при генерации новых узлов). */
+export function escapeXmlText(s) {
+    return s.replace(/[<>&]/g, (c) => (c === '<' ? '&lt;' : c === '>' ? '&gt;' : '&amp;'));
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { ConfluenceClient, ConfluenceApiError, type ConfluencePage, type ConfluencePageStorage, type ConfluenceAttachment, type ConfluenceLabel, type AttachmentVersionData, type CreatePageOptions, } from './client/client.js';
 export { authHeader, loadConfigFromEnv, type ConfluenceAuthType, type ConfluenceConfig, type LoadConfigOptions, } from './client/config.js';
 export { Markdown } from './markdown/markdown.js';
-export { renderToStorage, extractPlaceholders, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, type AttachmentUrls, type ExtractedPlaceholders, } from './markdown/render.js';
+export { renderToStorage, extractPlaceholders, parsePlaceholder, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, type AttachmentUrls, type ExtractedPlaceholders, type PlaceholderRef, type RenderStorageOptions, } from './markdown/render.js';
 export { validateMarkdown, MarkdownValidationError, type ValidateOptions } from './markdown/validate.js';
 export * from './macros/index.js';
 export { convertBpmn, convertBpmnFolder, isBpmnFile, bpmnOutputName, BPMN_FILE_RE, type BpmnConversion, type BpmnImageFormat, type ConvertBpmnFolderOptions, } from './bpmn/convert.js';
@@ -10,5 +10,11 @@ export { Attachment, AttachmentService, toAttachmentVersion, SRC_SHA_SIDECAR_SUF
 export { Page, Table } from './pages/page.js';
 export { readTableFromConfluence, findTable, findTableInMacro, parseHtmlTable, decodeHtmlCell, renderMarkdownTable, escapeMdTableCell, readAndMapTable, type ColumnAlign, type TableColumn, } from './pages/tables.js';
 export { publishPage, computeContentHash, DEFAULT_HASH_PROPERTY_KEY, type PublishPageOptions, type PublishPageResult, type TableData, } from './publish/publish.js';
+export { isHttpUrl, remoteFilename, isSameConfluenceOrigin, remoteRequestHeaders, downloadToFile, } from './publish/remote.js';
 export { runPublish, type Here, type Build, type PublishPlan, type RunPublishOptions, } from './publish/runner.js';
+export { parseStorage, serializeStorage, decodeEntities, StorageParseError, type XNode, type XElement, } from './export/xhtml.js';
+export { canonicalize, compareStorage, type CNode, type CompareResult, type StorageDiff, } from './export/canonical.js';
+export { storageToMarkdown, type StorageToMarkdownOptions, type StorageToMarkdownResult, } from './export/to-markdown.js';
+export { roundTripStorage, roundTripPage, renderExportedMarkdown, type RoundTripResult, } from './export/roundtrip.js';
+export { exportPage, type ExportPageOptions, type ExportPageResult } from './export/export-page.js';
 export { confluence, ConfluenceWrapper } from './wrapper.js';

package/dist/index.js

@@ -3,7 +3,7 @@ export { ConfluenceClient, ConfluenceApiError, } from './client/client.js';
 export { authHeader, loadConfigFromEnv, } from './client/config.js';
 // Markdown
 export { Markdown } from './markdown/markdown.js';
-export { renderToStorage, extractPlaceholders, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, } from './markdown/render.js';
+export { renderToStorage, extractPlaceholders, parsePlaceholder, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, } from './markdown/render.js';
 export { validateMarkdown, MarkdownValidationError } from './markdown/validate.js';
 // Macros (pluggable)
 export * from './macros/index.js';
@@ -17,6 +17,13 @@ export { Page, Table } from './pages/page.js';
 export { readTableFromConfluence, findTable, findTableInMacro, parseHtmlTable, decodeHtmlCell, renderMarkdownTable, escapeMdTableCell, readAndMapTable, } from './pages/tables.js';
 // Publish
 export { publishPage, computeContentHash, DEFAULT_HASH_PROPERTY_KEY, } from './publish/publish.js';
+export { isHttpUrl, remoteFilename, isSameConfluenceOrigin, remoteRequestHeaders, downloadToFile, } from './publish/remote.js';
 export { runPublish, } from './publish/runner.js';
+// Export (storage → markdown) & round-trip
+export { parseStorage, serializeStorage, decodeEntities, StorageParseError, } from './export/xhtml.js';
+export { canonicalize, compareStorage, } from './export/canonical.js';
+export { storageToMarkdown, } from './export/to-markdown.js';
+export { roundTripStorage, roundTripPage, renderExportedMarkdown, } from './export/roundtrip.js';
+export { exportPage } from './export/export-page.js';
 // Facade
 export { confluence, ConfluenceWrapper } from './wrapper.js';

package/dist/macros/builder.d.ts

@@ -26,5 +26,12 @@ export declare class MacroBuilder {
  *   macro('table-excerpt').param('name', 'data').body(md).toMarkdown()
  */
 export declare function macro(name: string): MacroBuilder;
+/**
+ * Экранирование значения параметра для однострочного маркера-комментария.
+ * Кодируются: `%` (первым — иначе двойное декодирование), `=`/`:`
+ * (разделители маркера), `<`/`>` (чтобы значение с `-->` не оборвало
+ * комментарий) и переводы строк (маркер обязан остаться одной строкой —
+ * нужно для многострочных параметров вроде SQL у table-joiner).
+ */
 export declare function escapeParamValue(s: string): string;
 export declare function unescapeParamValue(s: string): string;

package/dist/macros/builder.js

@@ -50,9 +50,30 @@ export class MacroBuilder {
 export function macro(name) {
     return new MacroBuilder(name);
 }
+/**
+ * Экранирование значения параметра для однострочного маркера-комментария.
+ * Кодируются: `%` (первым — иначе двойное декодирование), `=`/`:`
+ * (разделители маркера), `<`/`>` (чтобы значение с `-->` не оборвало
+ * комментарий) и переводы строк (маркер обязан остаться одной строкой —
+ * нужно для многострочных параметров вроде SQL у table-joiner).
+ */
 export function escapeParamValue(s) {
-    return s.replace(/[=:]/g, (c) => (c === '=' ? '%3D' : '%3A'));
+    return s
+        .replace(/%/g, '%25')
+        .replace(/=/g, '%3D')
+        .replace(/:/g, '%3A')
+        .replace(/</g, '%3C')
+        .replace(/>/g, '%3E')
+        .replace(/\r/g, '%0D')
+        .replace(/\n/g, '%0A');
 }
 export function unescapeParamValue(s) {
-    return s.replace(/%3D/g, '=').replace(/%3A/g, ':');
+    return s
+        .replace(/%0A/g, '\n')
+        .replace(/%0D/g, '\r')
+        .replace(/%3E/g, '>')
+        .replace(/%3C/g, '<')
+        .replace(/%3A/g, ':')
+        .replace(/%3D/g, '=')
+        .replace(/%25/g, '%');
 }

package/dist/macros/index.d.ts

@@ -6,7 +6,7 @@ export { coreMacrosPlugin, extractPlainText } from './plugins/core.js';
 export { tableFilterPlugin, TABLE_FILTER_DEFAULTS } from './plugins/table-filter.js';
 import { MacroRegistry } from './registry.js';
 import { anchor, children, codeBlock, excerpt, excerptInclude, expand, includePage, jiraIssue, panel, status, toc } from './plugins/core.js';
-import { tableExcerpt, tableExcerptInclude, tableFilter } from './plugins/table-filter.js';
+import { tableExcerpt, tableExcerptInclude, tableFilter, tableJoiner } from './plugins/table-filter.js';
 /** Creates a registry pre-loaded with all built-in plugins. */
 export declare function createDefaultRegistry(): MacroRegistry;
 /**
@@ -41,4 +41,5 @@ export declare const macros: {
     tableExcerpt: typeof tableExcerpt;
     tableFilter: typeof tableFilter;
     tableExcerptInclude: typeof tableExcerptInclude;
+    tableJoiner: typeof tableJoiner;
 };

package/dist/macros/index.js

@@ -8,7 +8,7 @@ import { MacroRegistry } from './registry.js';
 import { coreMacrosPlugin } from './plugins/core.js';
 import { tableFilterPlugin } from './plugins/table-filter.js';
 import { anchor, children, codeBlock, excerpt, excerptInclude, expand, includePage, info, jiraIssue, note, panel, status, tip, toc, warning, } from './plugins/core.js';
-import { tableExcerpt, tableExcerptInclude, tableFilter } from './plugins/table-filter.js';
+import { tableExcerpt, tableExcerptInclude, tableFilter, tableJoiner } from './plugins/table-filter.js';
 /** Creates a registry pre-loaded with all built-in plugins. */
 export function createDefaultRegistry() {
     return new MacroRegistry().use(coreMacrosPlugin).use(tableFilterPlugin);
@@ -47,4 +47,5 @@ export const macros = {
     tableExcerpt,
     tableFilter,
     tableExcerptInclude,
+    tableJoiner,
 };

package/dist/macros/plugins/core.js

@@ -109,6 +109,8 @@ export const coreMacrosPlugin = {
         richBodyMacro('tip', ['title', 'icon']),
         richBodyMacro('panel'),
         richBodyMacro('excerpt', ['hidden', 'atlassian-macro-output-type']),
+        // Page Properties (details) + Page Properties Report (detailssummary)
+        richBodyMacro('details'),
         // Plain-text body
         codeMacro,
         // Bodyless
@@ -118,6 +120,7 @@ export const coreMacrosPlugin = {
         bodylessMacro('children'),
         bodylessMacro('pagetree'),
         bodylessMacro('recently-updated'),
+        bodylessMacro('detailssummary'),
         anchorMacro,
         includeMacro,
         excerptIncludeMacro,

package/dist/macros/plugins/table-filter.d.ts

@@ -28,6 +28,14 @@ export declare function tableExcerpt(body: Markdown | string, name?: string, hid
  *   tableFilter(tableExcerptMd, { totalrow: ',,,Sum,Sum,Sum' })
  */
 export declare function tableFilter(body: Markdown | string, opts?: Record<string, string | undefined>): Markdown;
+/**
+ * Обёртывает markdown (обычно table-excerpt-include'ы) в макрос
+ * "объединение таблиц" с SQL-запросом. Многострочный SQL допустим.
+ *
+ * @example
+ *   tableJoiner(includesMd, "SELECT * FROM T1 LEFT JOIN T2 ON T1.'Код' = T2.'Код'")
+ */
+export declare function tableJoiner(body: Markdown | string, sql: string, opts?: Record<string, string | undefined>): Markdown;
 /** Включение table-excerpt с другой страницы по имени выборки. */
 export declare function tableExcerptInclude(name: string, page: string, opts?: {
     space?: string;

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

@@ -89,15 +89,37 @@ export const tableFilterPlugin = {
             }),
         },
         {
-            // Включение table-excerpt с другой страницы.
+            // Макрос "Объединение таблиц" (table-joiner): SQL-запрос по таблицам
+            // из тела макроса (обычно table-excerpt-include). Параметры — как есть;
+            // многострочный sql в маркере кодируется %0A (см. escapeParamValue).
+            name: 'table-joiner',
+            render: (ctx) => structuredMacro('table-joiner', ctx.macroId, {
+                params: ctx.params,
+                richBody: ctx.body,
+            }),
+        },
+        {
+            // Включение table-excerpt с другой страницы. page/space собираются в
+            // ac:link-параметр; остальные параметры (v, merge-tables, …)
+            // пробрасываются как есть.
             name: 'table-excerpt-include',
             render: (ctx) => {
                 const map = paramMap(ctx.params);
                 const params = [
                     { name: 'name', value: map.name ?? '' },
-                    { name: 'page', value: pageLinkValue(map.page ?? '', map.space), raw: true },
-                    { name: 'type', value: map.type ?? 'page' },
                 ];
+                // Без page макрос ссылается на текущую страницу — параметр не пишем.
+                if (map.page !== undefined) {
+                    params.push({ name: 'page', value: pageLinkValue(map.page, map.space), raw: true });
+                    params.push({ name: 'type', value: map.type ?? 'page' });
+                }
+                else if (map.type !== undefined) {
+                    params.push({ name: 'type', value: map.type });
+                }
+                for (const p of ctx.params) {
+                    if (!['name', 'page', 'space', 'type'].includes(p.name))
+                        params.push(p);
+                }
                 return structuredMacro('table-excerpt-include', ctx.macroId, { params });
             },
         },
@@ -144,6 +166,16 @@ export function tableFilter(body, opts = {}) {
     }
     return builder.toMarkdown();
 }
+/**
+ * Обёртывает markdown (обычно table-excerpt-include'ы) в макрос
+ * "объединение таблиц" с SQL-запросом. Многострочный SQL допустим.
+ *
+ * @example
+ *   tableJoiner(includesMd, "SELECT * FROM T1 LEFT JOIN T2 ON T1.'Код' = T2.'Код'")
+ */
+export function tableJoiner(body, sql, opts = {}) {
+    return macro('table-joiner').param('sql', sql).withParams(opts).body(body).toMarkdown();
+}
 /** Включение table-excerpt с другой страницы по имени выборки. */
 export function tableExcerptInclude(name, page, opts = {}) {
     const builder = macro('table-excerpt-include').param('name', name).param('page', page);

package/dist/macros/registry.d.ts

@@ -13,12 +13,23 @@ import type { MacroPlugin, MacroRenderer } from './types.js';
 export declare class MacroRegistry {
     private renderers;
     private pluginNames;
+    private passthroughUnknown;
     /** Registers all macros of a plugin. Later registrations win on name clash. */
     use(plugin: MacroPlugin): this;
     register(name: string, renderer: MacroRenderer): this;
     has(name: string): boolean;
     getRenderer(name: string): MacroRenderer | undefined;
     getAllRenderers(): Map<string, MacroRenderer>;
+    /**
+     * Управляет обработкой маркеров с именами, которых нет в реестре.
+     * По умолчанию ВКЛЮЧЕНО: такой маркер рендерится «как есть» —
+     * <ac:structured-macro> с параметрами из маркера и rich-text телом
+     * (если тело непустое). Это делает публикуемым любой макрос без явной
+     * регистрации (в т.ч. страницы, полученные из exportPage). Выключение
+     * возвращает старое поведение: незнакомый маркер остаётся комментарием.
+     */
+    passthroughUnknownMacros(enable?: boolean): this;
+    get allowsUnknownMacros(): boolean;
     /** Names of plugins registered via {@link use} (for diagnostics). */
     get plugins(): string[];
 }

package/dist/macros/registry.js

@@ -1,6 +1,6 @@
 import { Markdown } from '../markdown/markdown.js';
 import { unescapeParamValue } from './builder.js';
-import { generateMacroId } from './xml.js';
+import { generateMacroId, structuredMacro } from './xml.js';
 /**
  * Реестр макросов. Пустой при создании — наполняется плагинами через
  * {@link use} или точечной регистрацией через {@link register}.
@@ -14,6 +14,7 @@ import { generateMacroId } from './xml.js';
 export class MacroRegistry {
     renderers = new Map();
     pluginNames = [];
+    passthroughUnknown = true;
     /** Registers all macros of a plugin. Later registrations win on name clash. */
     use(plugin) {
         for (const def of plugin.macros) {
@@ -35,11 +36,34 @@ export class MacroRegistry {
     getAllRenderers() {
         return this.renderers;
     }
+    /**
+     * Управляет обработкой маркеров с именами, которых нет в реестре.
+     * По умолчанию ВКЛЮЧЕНО: такой маркер рендерится «как есть» —
+     * <ac:structured-macro> с параметрами из маркера и rich-text телом
+     * (если тело непустое). Это делает публикуемым любой макрос без явной
+     * регистрации (в т.ч. страницы, полученные из exportPage). Выключение
+     * возвращает старое поведение: незнакомый маркер остаётся комментарием.
+     */
+    passthroughUnknownMacros(enable = true) {
+        this.passthroughUnknown = enable;
+        return this;
+    }
+    get allowsUnknownMacros() {
+        return this.passthroughUnknown;
+    }
     /** Names of plugins registered via {@link use} (for diagnostics). */
     get plugins() {
         return [...this.pluginNames];
     }
 }
+/** Renderer «как есть» для макросов, не зарегистрированных в реестре. */
+function passthroughRenderer(name) {
+    return (ctx) => structuredMacro(name, ctx.macroId, {
+        params: ctx.params,
+        ...(ctx.body.trim() !== '' ? { richBody: ctx.body } : {}),
+    });
+}
+const ANY_START_MARKER_RE = /<!-- MACRO:start:([A-Za-z0-9_-]+)/g;
 /**
  * Преобразует маркеры макросов в XHTML storage format.
  * Обрабатывает вложенные макросы снизу вверх (от inner к outer).
@@ -61,9 +85,29 @@ export function processMacros(storage, registry) {
                 break;
             }
         }
+        // Незнакомые имена — passthrough-рендером (если разрешён). После
+        // зарегистрированных, чтобы явные рендереры всегда были в приоритете.
+        if (!modified && registry.allowsUnknownMacros) {
+            for (const name of findMarkerNames(content)) {
+                if (registry.has(name))
+                    continue;
+                const result = processMacroType(content, name, passthroughRenderer(name));
+                if (result !== content) {
+                    content = result;
+                    modified = true;
+                    break;
+                }
+            }
+        }
     }
     return new Markdown(content);
 }
+function findMarkerNames(storage) {
+    const names = new Set();
+    for (const m of storage.matchAll(ANY_START_MARKER_RE))
+        names.add(m[1]);
+    return names;
+}
 function processMacroType(storage, macroName, renderer) {
     // `:[^\n]*?` — lazy до конца строки маркера. Раньше тут было `[^-]*`,
     // что ломалось на дефис в имени параметра (например cell-width=) или

package/dist/markdown/render.d.ts

@@ -1,7 +1,22 @@
+/**
+ * Плейсхолдеры: `{{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[];
+    pages: string[];
 }
 export declare function extractPlaceholders(markdown: string): ExtractedPlaceholders;
 /**
@@ -15,6 +30,20 @@ export interface AttachmentUrls {
     images: Map<string, string>;
     files: Map<string, string>;
 }
+export interface RenderStorageOptions {
+    /**
+     * Как рендерить `{{img:...}}` / `{{file:...}}`:
+     *  - 'url' (default) — `<img src=…>` / `<a href=…>` с download-URL аттача;
+     *  - 'attachment' — нативные `<ac:image><ri:attachment/>` /
+     *    `<ac:link><ri:attachment/>` (ссылка по имени файла, URL не нужен).
+     *    Используется exportPage/round-trip: форма совпадает с тем, что
+     *    пишет сам Confluence.
+     */
+    imageStyle?: 'url' | 'attachment';
+    fileStyle?: 'url' | 'attachment';
+    /** Автопревращение голых URL в ссылки (default: true). */
+    linkify?: boolean;
+}
 export declare class MissingAttachmentUrlError extends Error {
     constructor(message: string);
 }
@@ -38,4 +67,4 @@ export declare class MissingAttachmentUrlError extends Error {
  * HTML этой проблемы лишена — `{{img:foo}}` мимо markdown-it проходит
  * посимвольно.
  */
-export declare function renderToStorage(markdown: string, urls: AttachmentUrls): string;
+export declare function renderToStorage(markdown: string, urls: AttachmentUrls, opts?: RenderStorageOptions): string;