mkdocs2confluence 0.9.1__tar.gz → 0.9.3__tar.gz

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.1
+Version: 0.9.3
 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
@@ -431,7 +431,11 @@ When `repo_url` + `edit_uri` are set in `mkdocs.yml`, a **Page source** footer p
 
 - **Edit this page** — links to the source file in your VCS (GitHub/GitLab/etc.)
 - **View history** — links to the file's commit history (derived automatically for GitHub and GitLab URLs)
-- **Last commit** — short commit SHA, message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
+- **Last commit** — short commit SHA (linked to that commit), message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
+
+### Section index child pages
+
+When a MkDocs navigation section has an `index.md`, the published Confluence page automatically includes the native **Children Display macro** below the page content. This renders a live, auto-maintained list of all direct child pages — no manual curation needed. The macro is injected by default on every section index page.
 
 ### Abbreviation expansion
 

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/README.md

@@ -391,7 +391,11 @@ When `repo_url` + `edit_uri` are set in `mkdocs.yml`, a **Page source** footer p
 
 - **Edit this page** — links to the source file in your VCS (GitHub/GitLab/etc.)
 - **View history** — links to the file's commit history (derived automatically for GitHub and GitLab URLs)
-- **Last commit** — short commit SHA, message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
+- **Last commit** — short commit SHA (linked to that commit), message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
+
+### Section index child pages
+
+When a MkDocs navigation section has an `index.md`, the published Confluence page automatically includes the native **Children Display macro** below the page content. This renders a live, auto-maintained list of all direct child pages — no manual curation needed. The macro is injected by default on every section index page.
 
 ### Abbreviation expansion
 

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.9.1"
+version = "0.9.3"
 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" }
@@ -73,6 +73,7 @@ select = ["E", "F", "I"]
 
 [tool.mypy]
 strict = true
+extra_checks = true
 python_version = "3.12"
 
 [[tool.mypy.overrides]]

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.1
+Version: 0.9.3
 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
@@ -431,7 +431,11 @@ When `repo_url` + `edit_uri` are set in `mkdocs.yml`, a **Page source** footer p
 
 - **Edit this page** — links to the source file in your VCS (GitHub/GitLab/etc.)
 - **View history** — links to the file's commit history (derived automatically for GitHub and GitLab URLs)
-- **Last commit** — short commit SHA, message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
+- **Last commit** — short commit SHA (linked to that commit), message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
+
+### Section index child pages
+
+When a MkDocs navigation section has an `index.md`, the published Confluence page automatically includes the native **Children Display macro** below the page content. This renders a live, auto-maintained list of all direct child pages — no manual curation needed. The macro is injected by default on every section index page.
 
 ### Abbreviation expansion
 

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -54,6 +54,7 @@ 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_children_macro.py
 tests/test_cli.py
 tests/test_editlink.py
 tests/test_emitter.py

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs_to_confluence/cli.py

@@ -359,7 +359,7 @@ def _cmd_preview(args: argparse.Namespace) -> None:
             for node in pages:
                 html_name = page_link_map.get(node.title, f"{Path(node.docs_path or node.title).stem}.html")
                 try:
-                    xhtml, _a, _l, _s = compile_page(node, config, link_map, quiet=args.quiet)
+                    xhtml, _a, _l, _s, _vm = compile_page(node, config, link_map, quiet=args.quiet)
                 except PageLoadError as exc:
                     print(f"  warning: skipping '{node.title}': {exc}", file=sys.stderr)
                     continue
@@ -417,7 +417,7 @@ def _cmd_preview(args: argparse.Namespace) -> None:
 
         def _build_page() -> None:
             try:
-                xhtml, _a, _l, _s = compile_page(page_node, config, link_map, quiet=True)
+                xhtml, _a, _l, _s, _vm = compile_page(page_node, config, link_map, quiet=True)
             except PageLoadError as exc:
                 print(f"  warning: {exc}", file=sys.stderr)
                 return
@@ -441,7 +441,7 @@ def _cmd_preview(args: argparse.Namespace) -> None:
         return
 
     try:
-        xhtml, _attachments, _labels, _status = compile_page(page_node, config, link_map, quiet=args.quiet)
+        xhtml, _attachments, _labels, _status, _vm = compile_page(page_node, config, link_map, quiet=args.quiet)
     except PageLoadError as exc:
         print(f"error: {exc}", file=sys.stderr)
         sys.exit(1)
@@ -656,7 +656,7 @@ def _cmd_pdf(args: argparse.Namespace) -> None:
     chapters: list[tuple[str, str]] = []
     for node in pages:
         try:
-            xhtml, _a, _l, _s = compile_page(node, config, link_map, quiet=args.quiet)
+            xhtml, _a, _l, _s, _vm = compile_page(node, config, link_map, quiet=args.quiet)
         except PageLoadError as exc:
             print(f"  warning: skipping '{node.title}': {exc}", file=sys.stderr)
             continue

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs_to_confluence/emitter/xhtml.py

@@ -27,6 +27,7 @@ from mkdocs_to_confluence.ir.nodes import (
     BlockQuote,
     BoldNode,
     BulletList,
+    ChildrenMacro,
     CodeBlock,
     CodeInlineNode,
     ContentTabs,
@@ -198,6 +199,8 @@ def _emit_node(node: IRNode) -> str:
         return _emit_grid_cards(node)
     if isinstance(node, SourceFooter):
         return _emit_source_footer(node)
+    if isinstance(node, ChildrenMacro):
+        return _emit_children_macro()
     if isinstance(node, UnsupportedBlock):
         return _emit_unsupported(node)
     # Inline nodes at block level (shouldn't normally appear, but be safe)
@@ -262,6 +265,15 @@ def _xml_safe(text: str) -> str:
     return html.escape(text).encode("ascii", "xmlcharrefreplace").decode()
 
 
+def _emit_children_macro() -> str:
+    """Emit the Confluence Children Display macro for section index pages."""
+    return (
+        '<ac:structured-macro ac:name="children">'
+        '<ac:parameter ac:name="depth">1</ac:parameter>'
+        "</ac:structured-macro>"
+    )
+
+
 def _emit_source_footer(node: SourceFooter) -> str:
     """Emit a borderless panel macro with edit/history links and last-commit info."""
     edit_href = html.escape(node.edit_url)

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs_to_confluence/ir/nodes.py

@@ -428,6 +428,15 @@ class FrontMatter(IRNode):
 # ── Abbreviation footnotes ────────────────────────────────────────────────────
 
 
+@dataclass(frozen=True)
+class ChildrenMacro(IRNode):
+    """Confluence Children Display macro listing direct child pages.
+
+    Appended to section index pages so readers see a live, auto-maintained
+    sub-page list.  Emitted as ``ac:structured-macro ac:name="children"``.
+    """
+
+
 @dataclass(frozen=True)
 class SourceFooter(IRNode):
     """Footer panel showing source-control links and last-commit info.

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs_to_confluence/publisher/client.py

@@ -255,6 +255,7 @@ class ConfluenceClient:
         version: int,
         *,
         parent_id: str | None = None,
+        version_message: str | None = None,
     ) -> dict[str, Any]:
         """Update an existing page to a new version and return the page dict.
 
@@ -273,7 +274,7 @@ class ConfluenceClient:
             },
             "version": {
                 "number": version,
-                "message": "Updated by mk2conf",
+                "message": version_message or "Published by mk2conf",
                 "minorEdit": True,
             },
         }

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/src/mkdocs_to_confluence/publisher/pipeline.py

@@ -24,7 +24,7 @@ from typing import TYPE_CHECKING, Literal
 import yaml
 
 from mkdocs_to_confluence.emitter.xhtml import emit
-from mkdocs_to_confluence.ir.nodes import FrontMatter
+from mkdocs_to_confluence.ir.nodes import ChildrenMacro, FrontMatter, SourceFooter
 from mkdocs_to_confluence.loader.config import ConfluenceConfig, MkDocsConfig
 from mkdocs_to_confluence.loader.nav import NavNode
 from mkdocs_to_confluence.loader.page import PageLoadError, load_page
@@ -75,6 +75,7 @@ class PageAction:
     attachments: list[Path] = field(default_factory=list)
     labels: tuple[str, ...] = field(default_factory=tuple)
     confluence_status: str | None = None
+    version_message: str | None = None  # git commit message for Confluence version history
     is_folder: bool = False        # True when this action creates a Confluence folder
     parent_is_folder: bool = False  # True when the parent content is a folder
     # Set after execution:
@@ -138,8 +139,9 @@ def compile_page(
     config: MkDocsConfig,
     link_map: dict[str, str] | None = None,
     *,
+    is_section_index: bool = False,
     quiet: bool = False,
-) -> tuple[str, list[Path], tuple[str, ...], str | None]:
+) -> tuple[str, list[Path], tuple[str, ...], str | None, str | None]:
     """Run the full compile pipeline for one page.
 
     Returns
@@ -148,7 +150,7 @@ def compile_page(
         ``(xhtml_string, attachment_paths, labels, confluence_status)``
     """
     if node.source_path is None:
-        return "", [], (), None
+        return "", [], (), None, None
 
     raw = load_page(node)
 
@@ -190,22 +192,26 @@ def compile_page(
     site_url = config.page_site_url(node.docs_path or "")
     if site_url:
         ir_nodes = attach_source_url(ir_nodes, "", site_url)
+    if is_section_index:
+        ir_nodes = ir_nodes + (ChildrenMacro(),)
     if edit_url:
         abs_path = str(config.docs_dir / (node.docs_path or ""))
         footer = build_source_footer(edit_url, abs_path)
         ir_nodes = ir_nodes + (footer,)
 
-    # Extract labels and confluence_status from FrontMatter node.
+    # Extract labels, confluence_status, and version_message from IR nodes.
     labels: tuple[str, ...] = ()
     confluence_status: str | None = None
+    version_message: str | None = None
     for node_item in ir_nodes:
         if isinstance(node_item, FrontMatter):
             labels = node_item.labels
             confluence_status = node_item.confluence_status
-            break
+        if isinstance(node_item, SourceFooter) and node_item.commit_sha and node_item.commit_summary:
+            version_message = f"{node_item.commit_sha}: {node_item.commit_summary}"
 
     xhtml = emit(ir_nodes)
-    return xhtml, attachments, labels, confluence_status
+    return xhtml, attachments, labels, confluence_status, version_message
 
 
 def _xhtml_hash(xhtml: str) -> str:
@@ -279,8 +285,8 @@ def _plan_nodes(
                     if not quiet:
                         print(f"  compiling  '{clean_title}'  (section index)")
                     try:
-                        xhtml, attachments, labels, confluence_status = compile_page(
-                            index_child, config, link_map, quiet=quiet
+                        xhtml, attachments, labels, confluence_status, version_message = compile_page(
+                            index_child, config, link_map, is_section_index=True, quiet=quiet
                         )
                         existing = client.find_page(space_id, clean_title)
                         xhtml_h = _xhtml_hash(xhtml)
@@ -312,6 +318,7 @@ def _plan_nodes(
                             attachments=attachments,
                             labels=labels,
                             confluence_status=confluence_status,
+                            version_message=version_message,
                             page_id=str(existing["id"]) if existing is not None else None,
                             version=(
                                 existing["version"]["number"] if existing is not None else None
@@ -379,7 +386,9 @@ def _plan_nodes(
             if not quiet:
                 print(f"  compiling  '{clean_title}'")
             try:
-                xhtml, attachments, labels, confluence_status = compile_page(node, config, link_map, quiet=quiet)
+                xhtml, attachments, labels, confluence_status, version_message = compile_page(
+                    node, config, link_map, quiet=quiet
+                )
             except (PageLoadError, OSError) as exc:
                 if not quiet:
                     print(f"  skipping   '{clean_title}'  (error: {exc})")
@@ -419,6 +428,7 @@ def _plan_nodes(
                 attachments=attachments,
                 labels=labels,
                 confluence_status=confluence_status,
+                version_message=version_message,
                 page_id=str(existing["id"]) if existing is not None else None,
                 version=(
                     existing["version"]["number"] if existing is not None else None
@@ -588,6 +598,7 @@ def _execute_page_action(
                 action.xhtml or "",
                 action.version + 1,
                 parent_id=action.parent_id,
+                version_message=action.version_message,
             )
             report.updated += 1
         except ConfluenceError as upd_exc:

mkdocs2confluence-0.9.3/tests/test_children_macro.py

@@ -0,0 +1,107 @@
+"""Tests for the ChildrenMacro IR node, emitter, and pipeline integration."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+from mkdocs_to_confluence.emitter.xhtml import emit
+from mkdocs_to_confluence.ir.nodes import ChildrenMacro
+from mkdocs_to_confluence.publisher.pipeline import compile_page
+
+# ── Emitter ───────────────────────────────────────────────────────────────────
+
+
+def test_children_macro_emits_structured_macro() -> None:
+    """ChildrenMacro must emit the Confluence children structured macro."""
+    xhtml = emit((ChildrenMacro(),))
+    assert 'ac:name="children"' in xhtml
+    assert 'ac:parameter ac:name="depth"' in xhtml
+    assert ">1<" in xhtml
+
+
+def test_children_macro_no_extra_params() -> None:
+    """Children macro must not emit sort/style params — Confluence defaults are fine."""
+    xhtml = emit((ChildrenMacro(),))
+    assert "sort" not in xhtml
+    assert "style" not in xhtml
+
+
+# ── Pipeline integration ──────────────────────────────────────────────────────
+
+
+def test_compile_page_section_index_includes_children_macro(tmp_path: Path) -> None:
+    """is_section_index=True must inject ChildrenMacro into emitted XHTML."""
+    from mkdocs_to_confluence.loader.config import MkDocsConfig
+
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    md = docs / "index.md"
+    md.write_text("# Section\n\nIntro text.\n", encoding="utf-8")
+
+    node = _page_node("Section", md)
+    config = MkDocsConfig(site_name="Test", docs_dir=docs, repo_url=None, edit_uri=None, nav=None)
+
+    xhtml, _, _, _, _ = compile_page(node, config, is_section_index=True)
+
+    assert 'ac:name="children"' in xhtml
+
+
+def test_compile_page_non_index_excludes_children_macro(tmp_path: Path) -> None:
+    """Regular pages must NOT include the ChildrenMacro."""
+    from mkdocs_to_confluence.loader.config import MkDocsConfig
+
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    md = docs / "guide.md"
+    md.write_text("# Guide\n\nContent.\n", encoding="utf-8")
+
+    node = _page_node("Guide", md)
+    config = MkDocsConfig(site_name="Test", docs_dir=docs, repo_url=None, edit_uri=None, nav=None)
+
+    xhtml, _, _, _, _ = compile_page(node, config, is_section_index=False)
+
+    assert 'ac:name="children"' not in xhtml
+
+
+def test_compile_page_children_macro_before_footer(tmp_path: Path) -> None:
+    """ChildrenMacro must appear before the source footer in the XHTML."""
+    from mkdocs_to_confluence.loader.config import MkDocsConfig
+
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    md = docs / "index.md"
+    md.write_text("# Section\n\nIntro.\n", encoding="utf-8")
+
+    node = _page_node("Section", md)
+    config = MkDocsConfig(
+        site_name="Test",
+        docs_dir=docs,
+        repo_url="https://github.com/org/repo",
+        edit_uri="edit/main/docs/",
+        nav=None,
+    )
+
+    with patch(
+        "mkdocs_to_confluence.transforms.footer._last_commit_info", return_value=None
+    ):
+        xhtml, _, _, _, _ = compile_page(node, config, is_section_index=True)
+
+    children_pos = xhtml.find('ac:name="children"')
+    panel_pos = xhtml.find('ac:name="panel"')
+    assert children_pos != -1
+    assert panel_pos != -1
+    assert children_pos < panel_pos
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _page_node(title: str, path: Path) -> object:
+    from mkdocs_to_confluence.loader.nav import NavNode
+
+    return NavNode(
+        title=title,
+        docs_path=path.name,
+        source_path=path,
+        level=0,
+        children=(),
+    )

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/tests/test_cli.py

@@ -175,7 +175,7 @@ class TestQuietOutputBehavior:
         yml = _minimal_config(tmp_path)
         (tmp_path / "docs" / "index.md").write_text("# Home\n\nHello.", encoding="utf-8")
 
-        mock_compile = MagicMock(return_value=("<p>Hello</p>", [], (), None))
+        mock_compile = MagicMock(return_value=("<p>Hello</p>", [], (), None, None))
         with patch("mkdocs_to_confluence.cli.compile_page", mock_compile), \
              patch("sys.stdout.isatty", return_value=False):
             flags = ["--quiet"] if quiet else []
@@ -223,7 +223,7 @@ class TestWatchFlag:
         yml = _minimal_config(tmp_path)
         (tmp_path / "docs" / "index.md").write_text("# Home\n", encoding="utf-8")
 
-        mock_compile = MagicMock(return_value=("<p>Hello</p>", [], (), None))
+        mock_compile = MagicMock(return_value=("<p>Hello</p>", [], (), None, None))
         mock_render = MagicMock(return_value="<html>preview</html>")
 
         with patch("mkdocs_to_confluence.cli.compile_page", mock_compile), \

{mkdocs2confluence-0.9.1 → mkdocs2confluence-0.9.3}/tests/test_publish_pipeline.py

@@ -53,7 +53,7 @@ def test_compile_page_returns_xhtml(tmp_path: Path) -> None:
 
     node = _page_node("Index", md)
     config = _make_config(docs)
-    xhtml, attachments, labels, _ = compile_page(node, config)
+    xhtml, attachments, labels, _, _ = compile_page(node, config)
 
     assert "<h1>" in xhtml or "Hello" in xhtml
     assert attachments == []
@@ -68,7 +68,7 @@ def test_compile_page_with_ready_false_still_compiles(tmp_path: Path) -> None:
 
     node = _page_node("Draft", md)
     config = _make_config(docs)
-    xhtml, attachments, labels, _ = compile_page(node, config)
+    xhtml, attachments, labels, _, _ = compile_page(node, config)
     # Still compiles fine; plan_publish is the gatekeeper
     assert isinstance(xhtml, str)
 
@@ -78,7 +78,7 @@ def test_compile_page_with_source_path_none_returns_empty(tmp_path: Path) -> Non
     docs.mkdir()
     node = NavNode(title="Missing", docs_path="missing.md", source_path=None, level=0)
     config = _make_config(docs)
-    xhtml, attachments, labels, _ = compile_page(node, config)
+    xhtml, attachments, labels, _, _ = compile_page(node, config)
     assert xhtml == ""
     assert attachments == []
     assert labels == ()
@@ -179,7 +179,7 @@ def test_plan_publish_skips_when_content_unchanged(tmp_path: Path) -> None:
 
     # Compile once to get the real hash
     from mkdocs_to_confluence.publisher.pipeline import compile_page
-    xhtml, _, _, _ = compile_page(node, config)
+    xhtml, _, _, _, _ = compile_page(node, config)
     stored_hash = _xhtml_hash(xhtml)
 
     existing_page = {"id": "77", "version": {"number": 2}}
@@ -1672,7 +1672,7 @@ class TestExecutePublishHelpers:
 
         assert report.updated == 1
         client.update_page.assert_called_once_with(
-            "existing-9", "P", "<p/>", 4, parent_id="ROOT"
+            "existing-9", "P", "<p/>", 4, parent_id="ROOT", version_message=None
         )
         client.create_page.assert_not_called()
 
@@ -2036,7 +2036,7 @@ def test_compile_page_returns_confluence_status(tmp_path: Path) -> None:
 
     node = _page_node("My Page", md)
     config = _make_config(docs)
-    _, _, _, confluence_status = compile_page(node, config)
+    _, _, _, confluence_status, _ = compile_page(node, config)
 
     assert confluence_status == "in-progress"
 
@@ -2060,7 +2060,7 @@ def test_compile_page_returns_confluence_status_with_repo_url(tmp_path: Path) ->
         edit_uri="edit/main/docs/",
         nav=None,
     )
-    _, _, _, confluence_status = compile_page(node, config)
+    _, _, _, confluence_status, _ = compile_page(node, config)
 
     assert confluence_status == "in-progress"
 
@@ -2098,7 +2098,7 @@ def test_plan_publish_sets_confluence_status_on_skip(tmp_path: Path) -> None:
     config = _make_config(docs)
     conf_config = _make_conf_config()
 
-    xhtml, _, _, _ = compile_page(node, config)
+    xhtml, _, _, _, _ = compile_page(node, config)
     stored_hash = _xhtml_hash(xhtml)
 
     existing_page = {"id": "77", "version": {"number": 2}}