mkdocs2confluence 0.9.2__tar.gz → 0.9.4__tar.gz

{mkdocs2confluence-0.9.2 → mkdocs2confluence-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.2
+Version: 0.9.4
 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.2 → mkdocs2confluence-0.9.4}/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.2 → mkdocs2confluence-0.9.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.9.2"
+version = "0.9.4"
 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" }

{mkdocs2confluence-0.9.2 → mkdocs2confluence-0.9.4}/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.2
+Version: 0.9.4
 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.2 → mkdocs2confluence-0.9.4}/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.2 → mkdocs2confluence-0.9.4}/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.2 → mkdocs2confluence-0.9.4}/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.2 → mkdocs2confluence-0.9.4}/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, SourceFooter
+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
@@ -139,6 +139,7 @@ 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, str | None]:
     """Run the full compile pipeline for one page.
@@ -168,6 +169,8 @@ def compile_page(
     preprocessed = expand_link_refs(preprocessed, link_defs)
     preprocessed = strip_link_defs(preprocessed)
     ir_nodes = parse(preprocessed)
+    if is_section_index:
+        ir_nodes = ir_nodes + (ChildrenMacro(),)
     ir_nodes = apply_abbreviations(ir_nodes, abbrevs, page_text=preprocessed)
     ir_nodes, attachments = resolve_local_assets(
         ir_nodes,
@@ -283,7 +286,7 @@ def _plan_nodes(
                         print(f"  compiling  '{clean_title}'  (section index)")
                     try:
                         xhtml, attachments, labels, confluence_status, version_message = compile_page(
-                            index_child, config, link_map, quiet=quiet
+                            index_child, config, link_map, is_section_index=True, quiet=quiet
                         )
                         existing = client.find_page(space_id, clean_title)
                         xhtml_h = _xhtml_hash(xhtml)

mkdocs2confluence-0.9.4/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=(),
+    )