mkdocs2confluence 0.14.0__tar.gz → 0.16.0__tar.gz

{mkdocs2confluence-0.14.0/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.14.0
+Version: 0.16.0
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -53,6 +53,7 @@ Dynamic: license-file
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)
 [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![imports: import-linter](https://img.shields.io/badge/imports-linted-blue.svg)](https://github.com/seddonym/import-linter)
 [![SLSA Level 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/jeckyl2010/mkdocs2confluence/badge)](https://securityscorecards.dev/viewer/?uri=github.com/jeckyl2010/mkdocs2confluence)
 
@@ -159,9 +160,17 @@ confluence:
   parent_page_id: "123456"           # optional root page
   mermaid_render: kroki              # "kroki" (default) | "kroki:https://your-kroki" | "none"
   full_width: true                   # default: true
+  attachment_preview: false          # default: false — inline PDF/Office previews
   changelog: CHANGELOG.md           # optional: publish as a top-level "What's New" page
+  exclude_properties:                # optional: front matter keys to hide from Page Properties
+    - source_documents
+    - internal_ref
 ```
 
+`exclude_properties` lists raw front matter keys to omit from the Page Properties table (e.g. internal tooling fields). Matching is exact and case-sensitive; `title`, `tags`, and `status` keep their special behavior even if excluded from the table.
+
+`attachment_preview` (bool, default `false`) renders links to local PDF/Office files (`.pdf`, `.doc(x)`, `.xls(x)`, `.ppt(x)`) as inline `view-file` previews instead of download links. Other file types always remain download links.
+
 The `confluence:` block is also accepted under `extra:` for MkDocs strict-mode compatibility. The API token is read from `token:` in `mkdocs.yml`, then `CONFLUENCE_API_TOKEN`, then `MK2CONF_TOKEN`.
 
 ### Changelog / What's New page

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/README.md

@@ -11,6 +11,7 @@
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)
 [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![imports: import-linter](https://img.shields.io/badge/imports-linted-blue.svg)](https://github.com/seddonym/import-linter)
 [![SLSA Level 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/jeckyl2010/mkdocs2confluence/badge)](https://securityscorecards.dev/viewer/?uri=github.com/jeckyl2010/mkdocs2confluence)
 
@@ -117,9 +118,17 @@ confluence:
   parent_page_id: "123456"           # optional root page
   mermaid_render: kroki              # "kroki" (default) | "kroki:https://your-kroki" | "none"
   full_width: true                   # default: true
+  attachment_preview: false          # default: false — inline PDF/Office previews
   changelog: CHANGELOG.md           # optional: publish as a top-level "What's New" page
+  exclude_properties:                # optional: front matter keys to hide from Page Properties
+    - source_documents
+    - internal_ref
 ```
 
+`exclude_properties` lists raw front matter keys to omit from the Page Properties table (e.g. internal tooling fields). Matching is exact and case-sensitive; `title`, `tags`, and `status` keep their special behavior even if excluded from the table.
+
+`attachment_preview` (bool, default `false`) renders links to local PDF/Office files (`.pdf`, `.doc(x)`, `.xls(x)`, `.ppt(x)`) as inline `view-file` previews instead of download links. Other file types always remain download links.
+
 The `confluence:` block is also accepted under `extra:` for MkDocs strict-mode compatibility. The API token is read from `token:` in `mkdocs.yml`, then `CONFLUENCE_API_TOKEN`, then `MK2CONF_TOKEN`.
 
 ### Changelog / What's New page

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.14.0"
+version = "0.16.0"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }
@@ -103,8 +103,36 @@ exclude_lines = [
   "raise NotImplementedError",
 ]
 
+# Architecture boundaries — enforces the compile pipeline stage separation
+# documented in .github/copilot-instructions.md. Higher layers may import lower
+# ones; siblings joined by "|" must stay independent of each other.
+[tool.importlinter]
+root_package = "mkdocs_to_confluence"
+
+[[tool.importlinter.contracts]]
+name = "Compiler pipeline stage layering"
+type = "layers"
+containers = ["mkdocs_to_confluence"]
+layers = [
+    "sync",
+    "publisher",
+    "compiler",
+    "preprocess | parser | transforms | emitter",
+    "ir | loader",
+]
+
+[[tool.importlinter.contracts]]
+name = "Renderer layering (preview/pdf)"
+type = "layers"
+containers = ["mkdocs_to_confluence"]
+layers = [
+    "pdf",
+    "preview",
+]
+
 [dependency-groups]
 dev = [
+    "import-linter>=2.11",
     "pip-audit>=2.10.0",
     "radon>=6.0.1",
     "vulture>=2.16",

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.14.0
+Version: 0.16.0
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -53,6 +53,7 @@ Dynamic: license-file
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)
 [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![imports: import-linter](https://img.shields.io/badge/imports-linted-blue.svg)](https://github.com/seddonym/import-linter)
 [![SLSA Level 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/jeckyl2010/mkdocs2confluence/badge)](https://securityscorecards.dev/viewer/?uri=github.com/jeckyl2010/mkdocs2confluence)
 
@@ -159,9 +160,17 @@ confluence:
   parent_page_id: "123456"           # optional root page
   mermaid_render: kroki              # "kroki" (default) | "kroki:https://your-kroki" | "none"
   full_width: true                   # default: true
+  attachment_preview: false          # default: false — inline PDF/Office previews
   changelog: CHANGELOG.md           # optional: publish as a top-level "What's New" page
+  exclude_properties:                # optional: front matter keys to hide from Page Properties
+    - source_documents
+    - internal_ref
 ```
 
+`exclude_properties` lists raw front matter keys to omit from the Page Properties table (e.g. internal tooling fields). Matching is exact and case-sensitive; `title`, `tags`, and `status` keep their special behavior even if excluded from the table.
+
+`attachment_preview` (bool, default `false`) renders links to local PDF/Office files (`.pdf`, `.doc(x)`, `.xls(x)`, `.ppt(x)`) as inline `view-file` previews instead of download links. Other file types always remain download links.
+
 The `confluence:` block is also accepted under `extra:` for MkDocs strict-mode compatibility. The API token is read from `token:` in `mkdocs.yml`, then `CONFLUENCE_API_TOKEN`, then `MK2CONF_TOKEN`.
 
 ### Changelog / What's New page

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/mkdocs_to_confluence/pdf/generator.py
 src/mkdocs_to_confluence/pdf/render.py
 src/mkdocs_to_confluence/preprocess/__init__.py
 src/mkdocs_to_confluence/preprocess/abbrevs.py
+src/mkdocs_to_confluence/preprocess/captions.py
 src/mkdocs_to_confluence/preprocess/fence.py
 src/mkdocs_to_confluence/preprocess/frontmatter.py
 src/mkdocs_to_confluence/preprocess/icons.py
@@ -58,19 +59,26 @@ src/mkdocs_to_confluence/sync/platform.py
 src/mkdocs_to_confluence/sync/state.py
 src/mkdocs_to_confluence/transforms/__init__.py
 src/mkdocs_to_confluence/transforms/abbrevs.py
+src/mkdocs_to_confluence/transforms/admonition_titles.py
 src/mkdocs_to_confluence/transforms/assets.py
+src/mkdocs_to_confluence/transforms/attachment_previews.py
+src/mkdocs_to_confluence/transforms/captions.py
 src/mkdocs_to_confluence/transforms/editlink.py
 src/mkdocs_to_confluence/transforms/footer.py
 src/mkdocs_to_confluence/transforms/images.py
 src/mkdocs_to_confluence/transforms/internallinks.py
 src/mkdocs_to_confluence/transforms/mermaid.py
 tests/test_abbrevs.py
+tests/test_admonition_titles.py
+tests/test_attachment_previews.py
+tests/test_captions.py
 tests/test_changelog_config.py
 tests/test_changelog_publish.py
 tests/test_children_macro.py
 tests/test_cli.py
 tests/test_editlink.py
 tests/test_emitter.py
+tests/test_exclude_properties_config.py
 tests/test_extra_css.py
 tests/test_footer.py
 tests/test_frontmatter.py

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/src/mkdocs_to_confluence/compiler/page.py

@@ -13,6 +13,7 @@ from mkdocs_to_confluence.preprocess.abbrevs import (
     extract_abbreviations,
     strip_abbreviation_defs,
 )
+from mkdocs_to_confluence.preprocess.captions import rewrite_figure_captions
 from mkdocs_to_confluence.preprocess.frontmatter import extract_front_matter
 from mkdocs_to_confluence.preprocess.icons import strip_icon_shortcodes
 from mkdocs_to_confluence.preprocess.includes import (
@@ -26,7 +27,14 @@ from mkdocs_to_confluence.preprocess.linkdefs import (
     strip_link_defs,
 )
 from mkdocs_to_confluence.transforms.abbrevs import apply_abbreviations
+from mkdocs_to_confluence.transforms.admonition_titles import (
+    strip_links_in_admonition_titles,
+)
 from mkdocs_to_confluence.transforms.assets import resolve_local_assets
+from mkdocs_to_confluence.transforms.attachment_previews import (
+    resolve_attachment_previews,
+)
+from mkdocs_to_confluence.transforms.captions import resolve_captions
 from mkdocs_to_confluence.transforms.editlink import attach_source_url
 from mkdocs_to_confluence.transforms.footer import build_source_footer
 from mkdocs_to_confluence.transforms.internallinks import resolve_internal_links
@@ -53,15 +61,22 @@ def compile_page(
         docs_dir=config.docs_dir,
     )
     preprocessed = strip_unsupported_html(preprocessed)
+    preprocessed = rewrite_figure_captions(preprocessed)
     preprocessed = strip_html_comments(preprocessed)
     preprocessed = strip_icon_shortcodes(preprocessed)
-    front_matter, preprocessed = extract_front_matter(preprocessed)
+    exclude_properties = (
+        config.confluence.exclude_properties if config.confluence else ()
+    )
+    front_matter, preprocessed = extract_front_matter(
+        preprocessed, exclude_properties=exclude_properties
+    )
     abbrevs = extract_abbreviations(preprocessed)
     preprocessed = strip_abbreviation_defs(preprocessed)
     link_defs = collect_link_defs(preprocessed)
     preprocessed = expand_link_refs(preprocessed, link_defs)
     preprocessed = strip_link_defs(preprocessed)
     ir_nodes = parse(preprocessed)
+    ir_nodes = strip_links_in_admonition_titles(ir_nodes, node.docs_path or "")
     if is_section_index:
         ir_nodes = ir_nodes + (ChildrenMacro(),)
     ir_nodes = apply_abbreviations(ir_nodes, abbrevs, page_text=preprocessed)
@@ -70,6 +85,11 @@ def compile_page(
         page_path=node.source_path,
         docs_dir=config.docs_dir,
     )
+    ir_nodes = resolve_captions(ir_nodes)
+    attachment_preview = (
+        config.confluence.attachment_preview if config.confluence else False
+    )
+    ir_nodes = resolve_attachment_previews(ir_nodes, enabled=attachment_preview)
     mermaid_render = config.confluence.mermaid_render if config.confluence else "kroki"
     if mermaid_render != "none":
         kroki_url = (

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/src/mkdocs_to_confluence/emitter/xhtml.py

@@ -25,6 +25,7 @@ from mkdocs_to_confluence.ir.nodes import (
     AbbrevGlossaryBlock,
     Admonition,
     AnchorNode,
+    AttachmentPreview,
     BlockQuote,
     BoldNode,
     BulletList,
@@ -685,6 +686,8 @@ def _emit_inline(node: IRNode) -> str:
         return f"<code{style_attr}>{html.escape(node.code)}</code>"
     if isinstance(node, LinkNode):
         return _emit_link(node)
+    if isinstance(node, AttachmentPreview):
+        return _emit_attachment_preview(node)
     if isinstance(node, ImageNode):
         return _emit_image(node)
     if isinstance(node, FootnoteRef):
@@ -709,6 +712,15 @@ def _emit_inline(node: IRNode) -> str:
     return html.escape(repr(node))
 
 
+def _emit_attachment_preview(node: AttachmentPreview) -> str:
+    filename = html.escape(node.filename, quote=True)
+    return (
+        '<ac:structured-macro ac:name="view-file">'
+        f'<ac:parameter ac:name="name"><ri:attachment ri:filename="{filename}"/></ac:parameter>'
+        "</ac:structured-macro>"
+    )
+
+
 def _emit_link(node: LinkNode) -> str:
     # Same-page anchor link: [text](#id) → ac:link with only ac:anchor.
     # Confluence strips a raw <a href="#id">, so it must use the anchor form.
@@ -758,14 +770,19 @@ def _emit_image(node: ImageNode) -> str:
     height_attr = f' ac:height="{node.height}"' if node.height is not None else ""
     align_attr = f' ac:align="{html.escape(node.align)}"' if node.align else ""
     size_attrs = width_attr + height_attr + align_attr
+    caption = (
+        f"<ac:caption><p>{html.escape(node.caption)}</p></ac:caption>"
+        if node.caption
+        else ""
+    )
     # Local file → attachment reference; URL → external ri:url
     src = node.src
     if src.startswith(("http://", "https://", "//", "data:")):
         ref = f'<ri:url ri:value="{html.escape(src)}"/>'
-        return f"<ac:image{alt_attr}{title_attr}{size_attrs}>{ref}</ac:image>"
+        return f"<ac:image{alt_attr}{title_attr}{size_attrs}>{ref}{caption}</ac:image>"
     else:
         filename = html.escape(node.attachment_name or Path(src).name)
         # data-local-path is used by the preview renderer only (not valid XHTML)
         local_attr = f' data-local-path="{html.escape(src)}"'
         ref = f'<ri:attachment ri:filename="{filename}"/>'
-        return f"<ac:image{alt_attr}{title_attr}{size_attrs}{local_attr}>{ref}</ac:image>"
+        return f"<ac:image{alt_attr}{title_attr}{size_attrs}{local_attr}>{ref}{caption}</ac:image>"

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/src/mkdocs_to_confluence/ir/nodes.py

@@ -162,6 +162,7 @@ class ImageNode(IRNode):
     src: str
     alt: str
     title: str | None = None
+    caption: str | None = None
     attachment_name: str | None = None
     width: int | None = None
     height: int | None = None
@@ -452,6 +453,18 @@ class ChildrenMacro(IRNode):
     """
 
 
+@dataclass(frozen=True)
+class AttachmentPreview(IRNode):
+    """An inline preview of an uploaded attachment (PDF/Office file).
+
+    ``filename`` is the collision-safe Confluence attachment name (the same
+    value carried on the originating ``LinkNode.attachment_name``). The emitter
+    renders a ``view-file`` macro referencing the attachment.
+    """
+
+    filename: str
+
+
 @dataclass(frozen=True)
 class SourceFooter(IRNode):
     """Footer panel showing source-control links and last-commit info.

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/src/mkdocs_to_confluence/loader/config.py

@@ -35,6 +35,8 @@ class ConfluenceConfig:
     github_base_branch: str = "main"        # base branch for review PRs
     allow_any_host: bool = False  # set True to allow non-Atlassian Cloud base_url hosts
     changelog_file: str | None = None  # path relative to docs_dir; None means disabled
+    exclude_properties: tuple[str, ...] = ()  # front matter keys to omit from Page Properties table
+    attachment_preview: bool = False  # render PDF/Office attachment links as view-file macros
 
 
 @dataclass(frozen=True)
@@ -276,6 +278,28 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
                     )
                 changelog_file = cl_str
 
+        # exclude_properties (optional) — raw front matter keys to omit from
+        # the Page Properties table. Pure list of literal keys, no wildcards.
+        raw_exclude = raw_conf.get("exclude_properties")
+        if raw_exclude is None:
+            exclude_properties: tuple[str, ...] = ()
+        elif isinstance(raw_exclude, list):
+            exclude_properties = tuple(str(k) for k in raw_exclude)
+        else:
+            raise ConfigError(
+                "mkdocs.yml: 'confluence.exclude_properties' must be a list of "
+                f"front matter keys, got {type(raw_exclude).__name__}."
+            )
+
+        # attachment_preview (optional) — render PDF/Office attachment links inline
+        raw_preview = raw_conf.get("attachment_preview", False)
+        if not isinstance(raw_preview, bool):
+            raise ConfigError(
+                "mkdocs.yml: 'confluence.attachment_preview' must be a boolean, "
+                f"got {type(raw_preview).__name__}."
+            )
+        attachment_preview = raw_preview
+
         confluence = ConfluenceConfig(
             base_url=base_url.rstrip("/"),
             space_key=space_key,
@@ -291,6 +315,8 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
             github_base_branch=str(raw_conf.get("github_base_branch", "main")),
             allow_any_host=allow_any_host,
             changelog_file=changelog_file,
+            exclude_properties=exclude_properties,
+            attachment_preview=attachment_preview,
         )
 
     # --- extra_css (optional) ---

mkdocs2confluence-0.16.0/src/mkdocs_to_confluence/preprocess/captions.py

@@ -0,0 +1,51 @@
+"""Figure/figcaption preprocess rewrite.
+
+Material for MkDocs authors captions with the ``md_in_html`` figure form::
+
+    <figure markdown="span">
+      ![alt](img.png)
+      <figcaption>The caption</figcaption>
+    </figure>
+
+Confluence storage format has no ``<figure>`` element, so this pass rewrites
+such a block into a single titled Markdown image::
+
+    ![alt](img.png "The caption")
+
+The image then flows through the normal parser and the ``resolve_captions``
+transform promotes the title to an ``ac:caption``. The figcaption text always
+wins over any pre-existing image title (it is substituted into the title slot).
+
+Limitations (graceful — non-matching blocks are left untouched):
+
+* The figcaption is treated as plain text (``[^<]*``); inline HTML such as
+  ``<em>`` inside a figcaption is not supported and the block is skipped.
+* An image with a trailing attr-list (``![a](x.png){ width=300 }``) is skipped.
+* ``src`` must be space-free (percent-encode spaces), per Markdown convention.
+"""
+
+from __future__ import annotations
+
+import re
+
+# The caption group is plain-text only (``[^<]*``) so it cannot run past a
+# missing ``</figcaption>`` and swallow a following ``<figure>`` block.
+_FIGURE_RE = re.compile(
+    r"<figure\b[^>]*>\s*"
+    r"!\[(?P<alt>[^\]]*)\]\((?P<src>[^\s)]+)(?:\s+\"[^\"]*\")?\)\s*"
+    r"<figcaption>(?P<cap>[^<]*)</figcaption>\s*"
+    r"</figure>",
+    re.IGNORECASE,
+)
+
+
+def rewrite_figure_captions(text: str) -> str:
+    """Rewrite ``<figure>…<figcaption>…</figure>`` blocks to titled images."""
+
+    def _sub(m: re.Match[str]) -> str:
+        alt = m.group("alt")
+        src = m.group("src")
+        cap = m.group("cap").strip().replace('"', "'")
+        return f'![{alt}]({src} "{cap}")'
+
+    return _FIGURE_RE.sub(_sub, text)

{mkdocs2confluence-0.14.0 → mkdocs2confluence-0.16.0}/src/mkdocs_to_confluence/preprocess/frontmatter.py

@@ -80,11 +80,16 @@ _FRONT_MATTER_RE = re.compile(r"\A---\s*\n(.*?\n?)---\s*\n?", re.DOTALL)
 # ── Public API ────────────────────────────────────────────────────────────────
 
 
-def extract_front_matter(text: str) -> tuple[FrontMatter | None, str]:
+def extract_front_matter(
+    text: str, exclude_properties: tuple[str, ...] = ()
+) -> tuple[FrontMatter | None, str]:
     """Parse YAML front matter from the top of *text*.
 
     Args:
         text: Raw markdown content.
+        exclude_properties: Raw front matter keys to omit from the Page
+            Properties table. Matching is exact and case-sensitive. Special
+            behaviors (title, tags->labels, status) are unaffected.
 
     Returns:
         A ``(FrontMatter | None, remaining_text)`` tuple.  ``FrontMatter`` is
@@ -105,14 +110,19 @@ def extract_front_matter(text: str) -> tuple[FrontMatter | None, str]:
     if not isinstance(raw, dict):
         return None, text
 
-    return _build_node(raw), remaining
+    return _build_node(raw, exclude_properties), remaining
 
 
 # ── Private helpers ───────────────────────────────────────────────────────────
 
 
-def _build_node(raw: dict[str, Any]) -> FrontMatter:
-    """Convert a raw front matter dict to a :class:`FrontMatter` IR node."""
+def _build_node(raw: dict[str, Any], exclude: tuple[str, ...] = ()) -> FrontMatter:
+    """Convert a raw front matter dict to a :class:`FrontMatter` IR node.
+
+    ``exclude`` lists raw keys to omit from the properties table (table rows
+    only — title/labels/status side-effects are computed independently below).
+    """
+    skip = _STRIP_FIELDS | set(exclude)
     title: str | None = _stringify(raw.get("title")) if "title" in raw else None
     subtitle: str | None = _stringify(raw.get("subtitle")) if "subtitle" in raw else None
 
@@ -129,14 +139,14 @@ def _build_node(raw: dict[str, Any]) -> FrontMatter:
     seen: set[str] = set()
 
     for key in _FIELD_ORDER:
-        if key in raw and key not in _STRIP_FIELDS and key != "subtitle":
+        if key in raw and key not in skip and key != "subtitle":
             display = _DISPLAY_NAMES.get(key, _humanize(key))
             properties.append((display, _format_value(key, raw[key])))
             seen.add(key)
 
     # Append any remaining unknown fields in document order.
     for key, value in raw.items():
-        if key in seen or key in _STRIP_FIELDS or key == "subtitle":
+        if key in seen or key in skip or key == "subtitle":
             continue
         display = _DISPLAY_NAMES.get(key, _humanize(key))
         properties.append((display, _format_value(key, value)))

mkdocs2confluence-0.16.0/src/mkdocs_to_confluence/transforms/admonition_titles.py

@@ -0,0 +1,55 @@
+"""Degrade Markdown links inside admonition titles.
+
+A Confluence macro title is an ``<ac:parameter>`` and holds plain text only —
+it cannot contain ``<ac:link>`` or any markup. A Markdown link written in an
+admonition title therefore cannot render. This transform replaces each inline
+link ``[text](target)`` in an ``Admonition`` title with its ``text`` and warns
+to stderr so the author can adjust the source.
+
+Images (``![alt](src)``) are deliberately left untouched (negative lookbehind on
+``!``). Reference-style links and autolinks are out of scope.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+import sys
+
+from mkdocs_to_confluence.ir.nodes import Admonition, IRNode, walk
+from mkdocs_to_confluence.ir.treeutil import replace_nodes
+
+# Inline Markdown link [text](target), but not an image (no leading '!').
+_LINK_RE = re.compile(r"(?<!!)\[([^\]]+)\]\(([^)]+)\)")
+
+
+def strip_links_in_admonition_titles(
+    nodes: tuple[IRNode, ...], page_path: str
+) -> tuple[IRNode, ...]:
+    """Replace inline links in admonition titles with their link text.
+
+    Emits a transpiler warning to stderr for each affected title. Returns the
+    original *nodes* unchanged when no title contained a link.
+    """
+    replacements: dict[int, IRNode] = {}
+
+    for top in nodes:
+        for node in walk(top):
+            if not isinstance(node, Admonition) or node.title is None:
+                continue
+            new_title = _LINK_RE.sub(r"\1", node.title)
+            if new_title == node.title:
+                continue
+            _warn(
+                "link in admonition title not supported by Confluence "
+                f'(using link text): "{node.title}" in {page_path}'
+            )
+            replacements[id(node)] = dataclasses.replace(node, title=new_title)
+
+    if not replacements:
+        return nodes
+    return replace_nodes(nodes, replacements)
+
+
+def _warn(msg: str) -> None:
+    print(f"  warning    {msg}", file=sys.stderr)

mkdocs2confluence-0.16.0/src/mkdocs_to_confluence/transforms/attachment_previews.py

@@ -0,0 +1,42 @@
+"""Attachment inline preview transform.
+
+When enabled, replaces ``LinkNode``s that point at an uploaded PDF or Office
+attachment (``attachment_name`` set by ``resolve_local_assets``) with an
+:class:`AttachmentPreview` node, which the emitter renders as a Confluence
+``view-file`` macro. Links to non-previewable file types, external URLs, and
+internal pages are left unchanged.
+"""
+
+from __future__ import annotations
+
+from mkdocs_to_confluence.ir.nodes import AttachmentPreview, IRNode, LinkNode, walk
+from mkdocs_to_confluence.ir.treeutil import replace_nodes
+
+PREVIEWABLE_EXTENSIONS: frozenset[str] = frozenset(
+    {".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx"}
+)
+
+
+def resolve_attachment_previews(
+    nodes: tuple[IRNode, ...], *, enabled: bool
+) -> tuple[IRNode, ...]:
+    """Swap eligible attachment links for ``AttachmentPreview`` nodes."""
+    if not enabled:
+        return nodes
+    replacements: dict[int, IRNode] = {}
+    for top_node in nodes:
+        for node in walk(top_node):
+            if not isinstance(node, LinkNode) or node.attachment_name is None:
+                continue
+            ext = _extension(node.attachment_name)
+            if ext not in PREVIEWABLE_EXTENSIONS:
+                continue
+            replacements[id(node)] = AttachmentPreview(filename=node.attachment_name)
+    if not replacements:
+        return nodes
+    return replace_nodes(nodes, replacements)
+
+
+def _extension(name: str) -> str:
+    dot = name.rfind(".")
+    return name[dot:].lower() if dot != -1 else ""

mkdocs2confluence-0.16.0/src/mkdocs_to_confluence/transforms/captions.py

@@ -0,0 +1,31 @@
+"""Caption resolution transform.
+
+Fills :attr:`ImageNode.caption` from the image ``title`` attribute when no
+caption is already present, and clears ``title`` so the same text is not also
+emitted as a hover tooltip. Images whose caption is already set (e.g. from a
+``<figcaption>`` rewrite) are left untouched, so figcaptions take precedence.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from mkdocs_to_confluence.ir.nodes import ImageNode, IRNode, walk
+from mkdocs_to_confluence.ir.treeutil import replace_nodes
+
+
+def resolve_captions(nodes: tuple[IRNode, ...]) -> tuple[IRNode, ...]:
+    """Promote image ``title`` to ``caption`` where no caption exists yet."""
+    replacements: dict[int, IRNode] = {}
+    for top_node in nodes:
+        for node in walk(top_node):
+            if not isinstance(node, ImageNode):
+                continue
+            if node.caption is not None or node.title is None:
+                continue
+            replacements[id(node)] = dataclasses.replace(
+                node, caption=node.title, title=None
+            )
+    if not replacements:
+        return nodes
+    return replace_nodes(nodes, replacements)