confluence-md-sync 0.6.0 → 0.8.0

package/README.md

@@ -25,6 +25,9 @@ npm install -g confluence-md-sync       # as a CLI: `confluence-md-sync …`
 - **Attachment dedup** — uploads are tagged `sha256:<hash>`; unchanged files
   are reused. `<file>.src-sha256` sidecars pin dedup to the *source* of
   non-deterministic artifacts (e.g. PNGs rendered by a headless browser).
+- **Managed-page banner** — optionally stamp a “edit this in <source>” notice
+  (info/warning panel with a link) into the page; injected into storage only,
+  never into the markdown source. See *Managed-page banner*.
 - **Fail before write** — placeholders, files and macro markers are validated
   up front; Confluence is never touched on a broken input.
 - **Pluggable macros** — built-in `core` + `table-filter` plugins, extend
@@ -121,6 +124,34 @@ await publishPage({
 }, cfg);
 ```
 
+### Managed-page banner
+
+When a page is generated from an external source (e.g. docs-studio) and users
+should not edit it in Confluence, add a `managedNotice`. It is injected into the
+**storage** at publish time — never into the markdown source, so export and
+round-trip stay clean, and git remains the single source of truth. The banner is
+deterministic (fixed macro id), so it doesn't break the no-history-spam hash skip.
+
+```ts
+await publishPage({
+  pageId,
+  markdownPath,
+  managedNotice: {
+    linkUrl: 'https://studio.example/doc/123',  // required
+    // everything below is optional:
+    linkText: 'постановка в docs-studio',       // default: 'docs-studio'
+    text: 'Правьте страницу в {link}. Здесь только чтение — правки будут перезаписаны.',
+    panel: 'warning',                           // info | note | warning | tip (default: info)
+    position: 'top',                            // 'top' (default) | 'bottom'
+  },
+}, cfg);
+```
+
+`{link}` in `text` is replaced by the link; omit it and the link is appended.
+The presence of `managedNotice` turns the banner on — leave it out and no notice
+is added. To apply one banner to every page of a CI plan, pass `managedNotice`
+to `runPublish(dir, plan, { managedNotice })`; a per-page value overrides it.
+
 ## BPMN diagrams out of the box
 
 Pass a `.bpmn` file as an image (a path or an `http(s)` URL) — it is
@@ -287,6 +318,31 @@ const rows = readCsv(decodeText(await page.getAttachment('data.csv')));
 
 ## Macros
 
+### Native Markdown syntax (0.8.0+)
+
+Popular macros are written (and exported back) as plain Markdown — no comment
+markers, no raw XHTML. Round-trip is verified canonically per macro; anything
+that doesn't fit falls back to markers/fenced blocks automatically.
+
+| Macro | Markdown |
+| --- | --- |
+| `info` / `note` / `warning` / `tip` | `> [!INFO] Title?` + quoted body (GitHub-style admonition) |
+| `details` (Page Properties) | `::: properties [id=…] [hidden=true]` + md-table + `:::` |
+| `expand` | `::: expand Title` + body + `:::` |
+| `panel` | `::: panel title=… borderColor=…` + body + `:::` |
+| `toc` | `{{toc}}` / `{{toc:maxLevel=3}}` |
+| `children` | `{{children}}` / `{{children:depth=2}}` |
+| `jira` | `{{jira:KEY-1}}` / `{{jira:jql=project = X\|maximumIssues=20}}` |
+| `status` | `{{status:Текст\|colour=Green\|subtle=true}}` |
+| `anchor` | `{{anchor:name}}` |
+| `detailssummary` (Page Properties Report) | `{{properties-report:cql=…\|firstcolumn=…}}` |
+
+Inside fenced code blocks the syntax is left untouched. The machine-readable
+list is exported as `nativeMacroList()`; the md→markers pass is
+`nativeToMarkers()` (runs automatically inside `renderToStorage`).
+
+### Marker builders
+
 Builders return `Markdown` with comment markers; markers become
 `<ac:structured-macro>` after rendering (nested macros resolve inner-first):
 

package/dist/export/to-markdown.d.ts

@@ -61,6 +61,8 @@ export interface StorageToMarkdownResult {
         rawHtml: number;
         /** readable-режим: сколько узлов конвертировано с потерей оформления. */
         lossy: number;
+        /** Макросы, выраженные нативным md-синтаксисом (панели, ::: …, {{…}}). */
+        native: number;
     };
 }
 /** Конвертирует storage-фрагмент страницы в Markdown. */

package/dist/export/to-markdown.js

@@ -79,7 +79,7 @@ class Converter {
     registry;
     images = new Set();
     files = new Set();
-    stats = { markers: 0, fenced: 0, rawHtml: 0, lossy: 0 };
+    stats = { markers: 0, fenced: 0, rawHtml: 0, lossy: 0, native: 0 };
     readable;
     localFiles;
     tablesAsRecords;
@@ -290,8 +290,147 @@ class Converter {
         return escapeMdText(textContent(el.children), {}, this.readable).trim();
     }
     // ── Макросы ──────────────────────────────────────────────────────────
+    // ── Нативный md-синтаксис (native.ts): панели, ::: properties/expand/panel,
+    // {{toc}}/{{children}}/{{jira}}/{{status}}/{{anchor}}/{{properties-report}}.
+    // Каждый кандидат проверяется рендером и канонической сверкой (как маркеры).
+    static NATIVE_ADMONITION_TAG = {
+        info: 'INFO', note: 'NOTE', warning: 'WARNING', tip: 'TIP',
+    };
+    static NATIVE_PLACEHOLDER_NAME = {
+        toc: 'toc', children: 'children', jira: 'jira', status: 'status',
+        anchor: 'anchor', detailssummary: 'properties-report',
+    };
+    tryNativeMd(el, name) {
+        if (this.readable)
+            return null; // readable-путь остаётся прежним
+        const parts = this.macroParts(el);
+        if (parts === null)
+            return null;
+        const { params, richBody, plainBody } = parts;
+        if (plainBody !== null)
+            return null;
+        const pmap = new Map(params.map((p) => [p.name, p.value]));
+        const oneline = (v) => v !== undefined && !/[\n|{}]/.test(v) && !v.includes('}}');
+        let candidate = null;
+        const tag = Converter.NATIVE_ADMONITION_TAG[name];
+        if (tag && richBody !== null) {
+            // Панель: параметры — только title.
+            if (![...pmap.keys()].every((k) => k === 'title'))
+                return null;
+            const title = pmap.get('title');
+            if (title !== undefined && (!oneline(title) || /\[|\]/.test(title)))
+                return null;
+            const bodyMd = this.bodyMd(richBody);
+            if (bodyMd === null || bodyMd.trim() === '')
+                return null;
+            const quoted = bodyMd.split('\n').map((l) => (l === '' ? '>' : `> ${l}`)).join('\n');
+            candidate = `> [!${tag}]${title ? ' ' + title : ''}\n${quoted}`;
+        }
+        else if (name === 'details' && richBody !== null) {
+            // «Свойства страницы»: параметры id/hidden, тело — простая md-таблица.
+            if (![...pmap.keys()].every((k) => k === 'id' || k === 'hidden'))
+                return null;
+            const bodyEls = elements(richBody.children);
+            const nonWs = richBody.children.filter((n) => !(n.kind === 'text' && /^[ \t\r\n]*$/.test(n.raw)));
+            if (bodyEls.length !== 1 || nonWs.length !== 1 || bodyEls[0].name !== 'table')
+                return null;
+            let tableMd;
+            try {
+                tableMd = this.tableToMd(bodyEls[0]);
+            }
+            catch (e) {
+                if (e instanceof Unrepresentable)
+                    return null;
+                throw e;
+            }
+            const dp = [...pmap.entries()].map(([k, v]) => (oneline(v) && !/["\s]/.test(v) ? ` ${k}=${v}` : null));
+            if (dp.some((x) => x === null))
+                return null;
+            candidate = `::: properties${dp.join('')}\n${tableMd}\n:::`;
+        }
+        else if (name === 'expand' && richBody !== null) {
+            if (![...pmap.keys()].every((k) => k === 'title'))
+                return null;
+            const title = pmap.get('title');
+            if (title !== undefined && (!oneline(title) || /=|"/.test(title)))
+                return null;
+            const bodyMd = this.bodyMd(richBody);
+            if (bodyMd === null)
+                return null;
+            candidate = `::: expand${title ? ' ' + title : ''}\n${bodyMd}\n:::`;
+        }
+        else if (Converter.NATIVE_PLACEHOLDER_NAME[name] && richBody === null) {
+            // Bodyless-плейсхолдеры. Части значений с | или }} не выразить — маркер.
+            const ph = Converter.NATIVE_PLACEHOLDER_NAME[name];
+            const attrs = [];
+            let head = '';
+            for (const p of params) {
+                if (!oneline(p.value) || p.value.includes('|'))
+                    return null;
+                if (name === 'jira' && p.name === 'key' && head === '') {
+                    head = p.value;
+                    continue;
+                }
+                if (name === 'status' && p.name === 'title' && head === '') {
+                    head = p.value;
+                    continue;
+                }
+                if (name === 'anchor' && (p.name === 'name' || p.name === '') && head === '') {
+                    head = p.value;
+                    continue;
+                }
+                const attrName = name === 'jira' && p.name === 'jqlQuery' ? 'jql' : p.name;
+                if (!/^[A-Za-z-]+$/.test(attrName))
+                    return null;
+                attrs.push(`${attrName}=${p.value}`);
+            }
+            const inner = [head, ...attrs].filter((s, i) => s !== '' || i > 0).join('|');
+            candidate = inner === '' ? `{{${ph}}}` : `{{${ph}:${inner}}}`;
+        }
+        if (candidate === null)
+            return null;
+        return this.verifyMacroMarker(el, candidate) ? candidate : null;
+    }
+    /** Разбирает macro-элемент на параметры и тела; null — посторонние дети. */
+    macroParts(el) {
+        const params = [];
+        let richBody = null;
+        let plainBody = null;
+        for (const child of elements(el.children)) {
+            if (child.name === 'ac:parameter') {
+                const pname = getAttr(child, 'ac:name') ?? '';
+                params.push({ name: pname, value: decodeEntities(textContent(child.children)) });
+            }
+            else if (child.name === 'ac:rich-text-body')
+                richBody = child;
+            else if (child.name === 'ac:plain-text-body')
+                plainBody = child;
+            else
+                return null;
+        }
+        return { params, richBody, plainBody };
+    }
+    /** Тело макроса → md; null, если не легло без потерь. */
+    bodyMd(richBody) {
+        const before = { images: new Set(this.images), files: new Set(this.files) };
+        try {
+            return this.blocksToMd(richBody.children).trimEnd();
+        }
+        catch (e) {
+            if (!(e instanceof Unrepresentable))
+                throw e;
+            this.images = before.images;
+            this.files = before.files;
+            return null;
+        }
+    }
     macroToMd(el) {
         const name = getAttr(el, 'ac:name') ?? '';
+        const nativeMd = this.tryNativeMd(el, name);
+        if (nativeMd !== null) {
+            this.stats.native++;
+            return nativeMd;
+        }
         const markerMd = this.tryMacroMarker(el, name);
         if (markerMd !== null) {
             this.stats.markers++;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { authHeader, loadConfigFromEnv, type ConfluenceAuthType, type Confluence
 export { Markdown } from './markdown/markdown.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 { nativeToMarkers, nativeMacroList, NATIVE_ADMONITIONS, NATIVE_DIRECTIVES, NATIVE_PLACEHOLDERS, } from './markdown/native.js';
 export * from './macros/index.js';
 export { convertBpmn, convertBpmnFolder, isBpmnFile, bpmnOutputName, BPMN_FILE_RE, type BpmnConversion, type BpmnImageFormat, type ConvertBpmnFolderOptions, } from './bpmn/convert.js';
 export { fileSha256, HASH_TAG_PREFIX } from './attachments/hash.js';
@@ -10,6 +11,7 @@ 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 { buildManagedNotice, applyManagedNotice, DEFAULT_MANAGED_NOTICE_TEXT, DEFAULT_MANAGED_NOTICE_LINK_TEXT, type ManagedNoticeOptions, } from './publish/notice.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';

package/dist/index.js

@@ -5,6 +5,7 @@ export { authHeader, loadConfigFromEnv, } from './client/config.js';
 export { Markdown } from './markdown/markdown.js';
 export { renderToStorage, extractPlaceholders, parsePlaceholder, renameImagePlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, } from './markdown/render.js';
 export { validateMarkdown, MarkdownValidationError } from './markdown/validate.js';
+export { nativeToMarkers, nativeMacroList, NATIVE_ADMONITIONS, NATIVE_DIRECTIVES, NATIVE_PLACEHOLDERS, } from './markdown/native.js';
 // Macros (pluggable)
 export * from './macros/index.js';
 // BPMN (optional peer dep 'bpmn-to-image' is loaded lazily on use)
@@ -17,6 +18,7 @@ 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 { buildManagedNotice, applyManagedNotice, DEFAULT_MANAGED_NOTICE_TEXT, DEFAULT_MANAGED_NOTICE_LINK_TEXT, } from './publish/notice.js';
 export { isHttpUrl, remoteFilename, isSameConfluenceOrigin, remoteRequestHeaders, downloadToFile, } from './publish/remote.js';
 export { runPublish, } from './publish/runner.js';
 // Export (storage → markdown) & round-trip

package/dist/markdown/native.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Нативный Markdown-синтаксис для популярных макросов Confluence.
+ * Сахар над маркерами <!-- MACRO:start/end -->: перед рендером native-
+ * конструкции переписываются в маркеры (nativeToMarkers), а экспорт
+ * (storage → md) эмитит их обратно с канонической верификацией.
+ *
+ * Перечень (см. README, раздел «Нативные макросы»):
+ *
+ *  Панели (admonition в стиле GitHub):
+ *    > [!INFO] Заголовок          → info   (заголовок опционален)
+ *    > [!NOTE] / [!WARNING] / [!TIP] → note / warning / tip
+ *    > текст панели — обычные строки цитаты после тега.
+ *
+ *  Блоки-директивы (fenced ::: … :::):
+ *    ::: properties [id=x] [hidden=true]   → details («Свойства страницы»;
+ *      тело — обычная md-таблица)            работает с отчётом detailssummary
+ *    ::: expand Заголовок                  → expand (разворачиваемый блок)
+ *    ::: panel title=… borderColor=…       → panel
+ *
+ *  Строчные плейсхолдеры (семейство {{img:}}/{{page:}}):
+ *    {{toc}} / {{toc:maxLevel=3}}          → toc (оглавление)
+ *    {{children}} / {{children:depth=2}}   → children (дочерние страницы)
+ *    {{jira:DR-123}}                       → jira (карточка задачи)
+ *    {{jira:jql=project = DR|maximumIssues=20}} → jira (выгрузка по JQL)
+ *    {{status:Готово|colour=Green}}        → status (лейбл)
+ *    {{anchor:имя}}                        → anchor (якорь)
+ *    {{properties-report:cql=label = "x"}} → detailssummary (отчёт по
+ *                                            свойствам страниц)
+ *
+ * Внутри fenced-код-блоков (``` / ~~~) синтаксис не интерпретируется.
+ */
+/** Панели: тег admonition → имя макроса. */
+export declare const NATIVE_ADMONITIONS: Record<string, string>;
+/** Блоки-директивы: имя директивы → имя макроса. */
+export declare const NATIVE_DIRECTIVES: Record<string, string>;
+/** Строчные плейсхолдеры: имя → имя макроса. */
+export declare const NATIVE_PLACEHOLDERS: Record<string, string>;
+/** Полный перечень макросов с нативной md-разметкой (для документации/UI). */
+export declare function nativeMacroList(): {
+    macro: string;
+    syntax: string;
+}[];
+/**
+ * Переписывает нативные конструкции в маркеры макросов. Идемпотентна для
+ * текста без нативного синтаксиса; содержимое fenced-код-блоков не трогает.
+ */
+export declare function nativeToMarkers(src: string): string;

package/dist/markdown/native.js

@@ -0,0 +1,232 @@
+/**
+ * Нативный Markdown-синтаксис для популярных макросов Confluence.
+ * Сахар над маркерами <!-- MACRO:start/end -->: перед рендером native-
+ * конструкции переписываются в маркеры (nativeToMarkers), а экспорт
+ * (storage → md) эмитит их обратно с канонической верификацией.
+ *
+ * Перечень (см. README, раздел «Нативные макросы»):
+ *
+ *  Панели (admonition в стиле GitHub):
+ *    > [!INFO] Заголовок          → info   (заголовок опционален)
+ *    > [!NOTE] / [!WARNING] / [!TIP] → note / warning / tip
+ *    > текст панели — обычные строки цитаты после тега.
+ *
+ *  Блоки-директивы (fenced ::: … :::):
+ *    ::: properties [id=x] [hidden=true]   → details («Свойства страницы»;
+ *      тело — обычная md-таблица)            работает с отчётом detailssummary
+ *    ::: expand Заголовок                  → expand (разворачиваемый блок)
+ *    ::: panel title=… borderColor=…       → panel
+ *
+ *  Строчные плейсхолдеры (семейство {{img:}}/{{page:}}):
+ *    {{toc}} / {{toc:maxLevel=3}}          → toc (оглавление)
+ *    {{children}} / {{children:depth=2}}   → children (дочерние страницы)
+ *    {{jira:DR-123}}                       → jira (карточка задачи)
+ *    {{jira:jql=project = DR|maximumIssues=20}} → jira (выгрузка по JQL)
+ *    {{status:Готово|colour=Green}}        → status (лейбл)
+ *    {{anchor:имя}}                        → anchor (якорь)
+ *    {{properties-report:cql=label = "x"}} → detailssummary (отчёт по
+ *                                            свойствам страниц)
+ *
+ * Внутри fenced-код-блоков (``` / ~~~) синтаксис не интерпретируется.
+ */
+import { escapeParamValue } from '../macros/builder.js';
+/** Панели: тег admonition → имя макроса. */
+export const NATIVE_ADMONITIONS = {
+    INFO: 'info',
+    NOTE: 'note',
+    WARNING: 'warning',
+    TIP: 'tip',
+};
+/** Блоки-директивы: имя директивы → имя макроса. */
+export const NATIVE_DIRECTIVES = {
+    properties: 'details',
+    expand: 'expand',
+    panel: 'panel',
+};
+/** Строчные плейсхолдеры: имя → имя макроса. */
+export const NATIVE_PLACEHOLDERS = {
+    toc: 'toc',
+    children: 'children',
+    jira: 'jira',
+    status: 'status',
+    anchor: 'anchor',
+    'properties-report': 'detailssummary',
+};
+/** Полный перечень макросов с нативной md-разметкой (для документации/UI). */
+export function nativeMacroList() {
+    return [
+        { macro: 'info', syntax: '> [!INFO] Заголовок?' },
+        { macro: 'note', syntax: '> [!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=… … :::' },
+        { macro: 'toc', syntax: '{{toc}} | {{toc:maxLevel=3}}' },
+        { macro: 'children', syntax: '{{children}} | {{children:depth=2}}' },
+        { macro: 'jira', syntax: '{{jira:KEY-1}} | {{jira:jql=…|maximumIssues=20}}' },
+        { macro: 'status', syntax: '{{status:Текст|colour=Green|subtle=true}}' },
+        { macro: 'anchor', syntax: '{{anchor:имя}}' },
+        { macro: 'detailssummary', syntax: '{{properties-report:cql=…|firstcolumn=…}}' },
+    ];
+}
+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 = /\{\{(toc|children|jira|status|anchor|properties-report)(?::((?:[^{}]|\{[^{])*?))?\}\}/g;
+const FENCE_RE = /^\s*(`{3,}|~{3,})/;
+/** Компактная пара маркеров без тела — для строчного контекста. */
+function inlineMarker(macroName, params) {
+    const paramStr = params.length
+        ? ':' + params.map((p) => `${escapeParamValue(p.name)}=${escapeParamValue(p.value)}`).join(':')
+        : '';
+    return `<!-- MACRO:start:${macroName}${paramStr} --><!-- MACRO:end:${macroName} -->`;
+}
+function blockMarker(macroName, params, body) {
+    const paramStr = params.length
+        ? ':' + params.map((p) => `${escapeParamValue(p.name)}=${escapeParamValue(p.value)}`).join(':')
+        : '';
+    return `<!-- MACRO:start:${macroName}${paramStr} -->\n${body}\n<!-- MACRO:end:${macroName} -->`;
+}
+/** `a|b=c|d=e` → первый сегмент + пары; поведение как у parsePlaceholder. */
+function splitAttrs(raw) {
+    const parts = raw.split('|');
+    const attrs = [];
+    for (const part of parts.slice(1)) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            attrs.push({ name: part.trim(), value: '' });
+        else
+            attrs.push({ name: part.slice(0, eq).trim(), value: part.slice(eq + 1).trim() });
+    }
+    return { head: parts[0].trim(), attrs };
+}
+/** Параметры плейсхолдера → параметры макроса Confluence. */
+function placeholderParams(kind, raw) {
+    if (raw === undefined || raw.trim() === '')
+        return [];
+    const { head, attrs } = splitAttrs(raw);
+    const params = [];
+    const headIsPair = head.includes('=');
+    if (headIsPair) {
+        const eq = head.indexOf('=');
+        attrs.unshift({ name: head.slice(0, eq).trim(), value: head.slice(eq + 1).trim() });
+    }
+    switch (kind) {
+        case 'jira':
+            if (!headIsPair && head !== '')
+                params.push({ name: 'key', value: head });
+            break;
+        case 'status':
+            if (!headIsPair && head !== '')
+                params.push({ name: 'title', value: head });
+            break;
+        case 'anchor':
+            if (!headIsPair && head !== '')
+                params.push({ name: 'name', value: head });
+            break;
+        default:
+            // toc/children/properties-report: только k=v-атрибуты.
+            if (!headIsPair && head !== '')
+                params.push({ name: head, value: '' });
+    }
+    for (const a of attrs) {
+        // jira: короткое `jql=` — алиас родного jqlQuery.
+        if (kind === 'jira' && a.name === 'jql')
+            params.push({ name: 'jqlQuery', value: a.value });
+        else
+            params.push(a);
+    }
+    return params;
+}
+function replaceInline(line) {
+    return line.replace(PLACEHOLDER_INLINE_RE, (_full, kind, raw) => inlineMarker(NATIVE_PLACEHOLDERS[kind], placeholderParams(kind, raw)));
+}
+/** Параметры директивы: токены `k=v` (значение можно в кавычках) + свободный текст → title. */
+function directiveParams(name, rest) {
+    const params = [];
+    if (!rest)
+        return params;
+    const free = [];
+    const re = /([A-Za-z-]+)=("([^"]*)"|\S+)|(\S+)/g;
+    for (const m of rest.matchAll(re)) {
+        if (m[1])
+            params.push({ name: m[1], value: m[3] ?? m[2] });
+        else
+            free.push(m[4]);
+    }
+    if (free.length && name === 'expand')
+        params.unshift({ name: 'title', value: free.join(' ') });
+    return params;
+}
+/**
+ * Переписывает нативные конструкции в маркеры макросов. Идемпотентна для
+ * текста без нативного синтаксиса; содержимое fenced-код-блоков не трогает.
+ */
+export function nativeToMarkers(src) {
+    const lines = src.split('\n');
+    const out = [];
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fm = FENCE_RE.exec(line);
+        if (fm) {
+            if (fence === null)
+                fence = fm[1][0];
+            else if (fm[1][0] === fence)
+                fence = null;
+            out.push(line);
+            continue;
+        }
+        if (fence !== null) {
+            out.push(line);
+            continue;
+        }
+        // ── Панели: > [!TYPE] Заголовок? ─────────────────────────────────────
+        const am = ADMONITION_FIRST_RE.exec(line);
+        const macroName = am ? NATIVE_ADMONITIONS[am[1].toUpperCase()] : undefined;
+        if (am && macroName) {
+            const body = [];
+            let j = i + 1;
+            for (; j < lines.length && /^>( |$)/.test(lines[j]); j++) {
+                body.push(lines[j].replace(/^> ?/, ''));
+            }
+            const params = am[2].trim() ? [{ name: 'title', value: am[2].trim() }] : [];
+            out.push(blockMarker(macroName, params, nativeToMarkers(body.join('\n'))));
+            i = j - 1;
+            continue;
+        }
+        // ── Директивы: ::: name … / ::: ──────────────────────────────────────
+        const dm = DIRECTIVE_OPEN_RE.exec(line);
+        const dirMacro = dm ? NATIVE_DIRECTIVES[dm[1]] : undefined;
+        if (dm && dirMacro) {
+            const body = [];
+            let j = i + 1;
+            let innerFence = null;
+            let closed = false;
+            for (; j < lines.length; j++) {
+                const bl = lines[j];
+                const bfm = FENCE_RE.exec(bl);
+                if (bfm) {
+                    if (innerFence === null)
+                        innerFence = bfm[1][0];
+                    else if (bfm[1][0] === innerFence)
+                        innerFence = null;
+                }
+                else if (innerFence === null && DIRECTIVE_CLOSE_RE.test(bl)) {
+                    closed = true;
+                    break;
+                }
+                body.push(bl);
+            }
+            if (closed) {
+                out.push(blockMarker(dirMacro, directiveParams(dm[1], dm[2]), nativeToMarkers(body.join('\n'))));
+                i = j;
+                continue;
+            }
+            // Незакрытая директива — оставляем как текст.
+        }
+        out.push(replaceInline(line));
+    }
+    return out.join('\n');
+}

package/dist/markdown/render.js

@@ -1,4 +1,5 @@
 import MarkdownIt from 'markdown-it';
+import { nativeToMarkers } from './native.js';
 // xhtmlOut: true — Confluence storage format = XHTML, void-элементы
 // (<hr/>, <br/>, <img/>) обязаны быть самозакрывающимися.
 // html: true — разрешить HTML (нужно для <!-- MACRO:... --> комментариев)
@@ -106,6 +107,9 @@ export class MissingAttachmentUrlError extends Error {
  * посимвольно.
  */
 export function renderToStorage(markdown, urls, opts = {}) {
+    // Нативный md-синтаксис макросов (панели, ::: properties, {{toc}} …) —
+    // сахар над маркерами: переписываем до markdown-it (см. native.ts).
+    markdown = nativeToMarkers(markdown);
     const renderer = opts.linkify === false ? mdNoLinkify : md;
     let html = renderer.render(markdown);
     // ```confluence-storage — транспорт для дословного XHTML (ac:/ri:-теги

package/dist/publish/notice.d.ts

@@ -0,0 +1,34 @@
+/**
+ * «Баннер управляемой страницы»: примечание о том, что страница ведётся во
+ * внешнем источнике (docs-studio), а правки в самой Confluence будут
+ * перезаписаны. Вставляется в storage при публикации, но НЕ в markdown-
+ * источник — round-trip/экспорт его не увидят, git остаётся чистым.
+ */
+export interface ManagedNoticeOptions {
+    /**
+     * URL источника (docs-studio / репозиторий постановки), куда ведёт ссылка.
+     * Обязателен — без него примечание не имеет смысла.
+     */
+    linkUrl: string;
+    /** Текст ссылки. Default: {@link DEFAULT_MANAGED_NOTICE_LINK_TEXT}. */
+    linkText?: string;
+    /**
+     * Текст примечания. Плейсхолдер `{link}` заменяется ссылкой; если его в
+     * тексте нет, ссылка добавляется в конец. Default:
+     * {@link DEFAULT_MANAGED_NOTICE_TEXT}.
+     */
+    text?: string;
+    /** Куда вставлять баннер: 'top' (шапка) или 'bottom' (низ). Default: 'top'. */
+    position?: 'top' | 'bottom';
+    /**
+     * Тип панели Confluence (влияет на цвет/иконку). Default: 'info'.
+     * 'warning' — красная, самый заметный вариант для «не редактировать».
+     */
+    panel?: 'info' | 'note' | 'warning' | 'tip';
+}
+export declare const DEFAULT_MANAGED_NOTICE_TEXT: string;
+export declare const DEFAULT_MANAGED_NOTICE_LINK_TEXT = "docs-studio";
+/** Строит storage-разметку баннера (одиночный `<ac:structured-macro>`). */
+export declare function buildManagedNotice(opts: ManagedNoticeOptions): string;
+/** Дописывает баннер в начало (top) или конец (bottom) storage-контента. */
+export declare function applyManagedNotice(storage: string, opts: ManagedNoticeOptions): string;

package/dist/publish/notice.js

@@ -0,0 +1,37 @@
+/**
+ * «Баннер управляемой страницы»: примечание о том, что страница ведётся во
+ * внешнем источнике (docs-studio), а правки в самой Confluence будут
+ * перезаписаны. Вставляется в storage при публикации, но НЕ в markdown-
+ * источник — round-trip/экспорт его не увидят, git остаётся чистым.
+ */
+import { structuredMacro } from '../macros/xml.js';
+import { escapeXmlAttr } from '../macros/xml.js';
+export const DEFAULT_MANAGED_NOTICE_TEXT = 'Страница синхронизируется автоматически. Вносите правки в источнике ({link}) — ' +
+    'ручные изменения на этой странице будут перезаписаны при следующей публикации.';
+export const DEFAULT_MANAGED_NOTICE_LINK_TEXT = 'docs-studio';
+// Фиксированный ac:macro-id: баннер обязан давать БАЙТ-В-БАЙТ одинаковый
+// storage при каждой публикации. Со случайным id (generateMacroId) content-
+// hash менялся бы каждый раз → страница вечно считалась бы изменённой.
+const NOTICE_MACRO_ID = '0f0e0d0c-0b0a-4009-8008-000000000001';
+/** Собирает `<a href>`-ссылку на источник. */
+function noticeLink(opts) {
+    const text = opts.linkText ?? DEFAULT_MANAGED_NOTICE_LINK_TEXT;
+    return `<a href="${escapeXmlAttr(opts.linkUrl)}">${escapeXmlAttr(text)}</a>`;
+}
+/** Строит storage-разметку баннера (одиночный `<ac:structured-macro>`). */
+export function buildManagedNotice(opts) {
+    if (!opts.linkUrl)
+        throw new Error('managedNotice: linkUrl is required');
+    const panel = opts.panel ?? 'info';
+    const link = noticeLink(opts);
+    const text = opts.text ?? DEFAULT_MANAGED_NOTICE_TEXT;
+    const inner = text.includes('{link}')
+        ? text.split('{link}').map(escapeXmlAttr).join(link)
+        : `${escapeXmlAttr(text)} ${link}`;
+    return structuredMacro(panel, NOTICE_MACRO_ID, { richBody: `<p>${inner}</p>` });
+}
+/** Дописывает баннер в начало (top) или конец (bottom) storage-контента. */
+export function applyManagedNotice(storage, opts) {
+    const notice = buildManagedNotice(opts);
+    return (opts.position ?? 'top') === 'bottom' ? `${storage}${notice}` : `${notice}${storage}`;
+}

package/dist/publish/publish.d.ts

@@ -1,5 +1,6 @@
 import type { ConfluenceConfig } from '../client/config.js';
 import { type RenderStorageOptions } from '../markdown/render.js';
+import { type ManagedNoticeOptions } from './notice.js';
 import type { MacroRegistry } from '../macros/registry.js';
 import { Markdown } from '../markdown/markdown.js';
 export interface TableData {
@@ -42,6 +43,13 @@ export interface PublishPageOptions {
     labels?: string[];
     /** Комментарий к версии страницы. */
     versionMessage?: string;
+    /**
+     * Примечание «страница управляется извне» (docs-studio). Вставляется в
+     * storage при публикации, НО не в markdown-источник — экспорт/round-trip
+     * его не увидят. Наличие опции включает баннер; настраиваются текст, ссылка,
+     * её текст, тип панели и позиция (шапка/низ). См. {@link ManagedNoticeOptions}.
+     */
+    managedNotice?: ManagedNoticeOptions;
     /** Свой реестр макросов (default: встроенные core + table-filter). */
     registry?: MacroRegistry;
     /**

package/dist/publish/publish.js

@@ -8,6 +8,7 @@ import { bpmnOutputName, convertBpmn, isBpmnFile } from '../bpmn/convert.js';
 import { downloadToFile, isHttpUrl, remoteFilename } from './remote.js';
 import { renameImagePlaceholders, renderToStorage, } from '../markdown/render.js';
 import { validateMarkdown } from '../markdown/validate.js';
+import { applyManagedNotice } from './notice.js';
 import { processMacros } from '../macros/registry.js';
 import { defaultMacroRegistry } from '../macros/index.js';
 import { Markdown } from '../markdown/markdown.js';
@@ -85,6 +86,10 @@ export async function publishPage(opts, cfg) {
     const tables = opts.tables ?? [];
     const registry = opts.registry ?? defaultMacroRegistry;
     const hashKey = opts.hashPropertyKey ?? DEFAULT_HASH_PROPERTY_KEY;
+    // Fail fast: баннер без ссылки бессмыслен — падаем до любого сетевого I/O.
+    if (opts.managedNotice && !opts.managedNotice.linkUrl) {
+        throw new Error('publishPage: managedNotice.linkUrl is required');
+    }
     // 0a. Удалённые источники: http(s)://-элементы в images[]/files[]
     //     заменяются на локальный путь в downloadDir с именем из URL — дальше
     //     конвейер (валидация, BPMN, аплоад) работает с обычными путями.
@@ -195,6 +200,13 @@ export async function publishPage(opts, cfg) {
     let storage = renderToStorage(markdown, urls, opts.render ?? {});
     // 2.5. Преобразование маркеров макросов в XHTML.
     storage = processMacros(storage, registry).toString();
+    // 2.6. Баннер «страница управляется извне». Вставляется здесь, в storage —
+    //   не в markdown — поэтому источник/round-trip его не содержат. Баннер
+    //   детерминирован (фиксированный macro-id), значит попадает в content-hash
+    //   стабильно и не ломает идемпотентность.
+    if (opts.managedNotice) {
+        storage = applyManagedNotice(storage, opts.managedNotice);
+    }
     if (opts.dryRun) {
         console.log(`[publish] dry-run: page ${pageId} rendered OK (${storage.length} bytes of storage)`);
         return {

package/dist/publish/runner.d.ts

@@ -1,4 +1,5 @@
 import { type PublishPageOptions, type PublishPageResult } from './publish.js';
+import type { ManagedNoticeOptions } from './notice.js';
 import { type ConfluenceConfig, type LoadConfigOptions } from '../client/config.js';
 export type Here = (relativePath: string) => string;
 export type Build = (relativePath: string) => string;
@@ -14,6 +15,12 @@ export interface RunPublishOptions {
      * соответствует компоновке репо `<repo>/docs/<set>` + `<repo>/build/<set>`.
      */
     buildDir?: string;
+    /**
+     * Баннер «страница управляется извне» по умолчанию для ВСЕХ страниц прогона
+     * (docs-studio). Значение, заданное у конкретной страницы в `managedNotice`,
+     * имеет приоритет. См. {@link ManagedNoticeOptions}.
+     */
+    managedNotice?: ManagedNoticeOptions;
 }
 /**
  * Минимальная точка входа для публикующего скрипта (`docs/<set>/publish.ts`).

package/dist/publish/runner.js

@@ -29,7 +29,11 @@ export async function runPublish(baseDir, plan, opts = {}) {
         const pages = typeof plan === 'function' ? await plan(here, build) : plan;
         const results = [];
         for (const page of pages) {
-            results.push(await publishPage(page, cfg));
+            // Дефолтный баннер прогона применяется, только если страница его не задала.
+            const merged = opts.managedNotice && page.managedNotice === undefined
+                ? { ...page, managedNotice: opts.managedNotice }
+                : page;
+            results.push(await publishPage(merged, cfg));
         }
         return results;
     }

package/package.json

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