mkdocs2confluence 0.5.28__tar.gz → 0.6.1__tar.gz

{mkdocs2confluence-0.5.28/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.5.28
+Version: 0.6.1
 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
@@ -41,6 +41,7 @@ Dynamic: license-file
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
+[![Downloads](https://img.shields.io/pypi/dm/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
 [![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
 [![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
 [![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
@@ -133,7 +134,7 @@ The `--html` flag renders Confluence macros as visual HTML panels so you can rev
 Compile all pages listed in `nav:` and publish them to Confluence Cloud.
 
 ```
-mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE] [--prune]
 ```
 
 | Flag | Default | Description |
@@ -143,6 +144,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
 | `--dry-run` | off | Print the publish plan without making any API calls |
 | `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+| `--prune` | off | Delete managed Confluence pages no longer in `nav:` (see [Orphan pruning](#orphan-pruning)) |
 
 #### Configuration
 
@@ -171,6 +173,19 @@ The API token is read from (in priority order):
 - Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
 - All locally linked assets are uploaded as Confluence page attachments automatically.
 - **Smart update detection** — before calling the Confluence update API, mk2conf compares a `sha256` hash of the compiled output against the hash stored from the previous run (kept as a hidden Confluence page property `mk2conf-content-hash`). Pages whose content has not changed are skipped entirely — no version bump, no watcher notification.
+- **Orphan pruning** — every page created by mk2conf is stamped with a hidden `mk2conf-managed` property. Pass `--prune` to automatically delete managed pages that have been removed from `nav:`. Manually-created Confluence pages are never deleted.
+
+#### Orphan pruning
+
+```bash
+mk2conf publish --prune
+```
+
+After each publish run, `--prune` fetches all descendants of the configured `parent_page_id`, diffs them against the pages just published, and deletes any managed orphans — i.e. pages that carry the `mk2conf-managed` stamp but are no longer in the MkDocs nav.
+
+> **Safety:** Only pages stamped by mk2conf are eligible for deletion. Any page created directly in Confluence will never be touched, even if it sits inside the managed hierarchy.
+>
+> **Partial runs:** `--prune` is silently ignored when `--page` or `--section` is used, because a partial publish would only cover a subset of the nav and would incorrectly identify out-of-scope pages as orphans.
 
 #### Mermaid rendering
 
@@ -321,7 +336,7 @@ Any unrecognised block is preserved as a visible `warning` macro — no content
 
 ## Roadmap
 
-- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+- [x] **Delete orphaned pages** — `--prune` detects and removes managed Confluence pages that have been removed from `nav:`. Manually-created pages are never deleted.
 
 ---
 

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/README.md

@@ -3,6 +3,7 @@
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
+[![Downloads](https://img.shields.io/pypi/dm/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
 [![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
 [![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
 [![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
@@ -95,7 +96,7 @@ The `--html` flag renders Confluence macros as visual HTML panels so you can rev
 Compile all pages listed in `nav:` and publish them to Confluence Cloud.
 
 ```
-mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE] [--prune]
 ```
 
 | Flag | Default | Description |
@@ -105,6 +106,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
 | `--dry-run` | off | Print the publish plan without making any API calls |
 | `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+| `--prune` | off | Delete managed Confluence pages no longer in `nav:` (see [Orphan pruning](#orphan-pruning)) |
 
 #### Configuration
 
@@ -133,6 +135,19 @@ The API token is read from (in priority order):
 - Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
 - All locally linked assets are uploaded as Confluence page attachments automatically.
 - **Smart update detection** — before calling the Confluence update API, mk2conf compares a `sha256` hash of the compiled output against the hash stored from the previous run (kept as a hidden Confluence page property `mk2conf-content-hash`). Pages whose content has not changed are skipped entirely — no version bump, no watcher notification.
+- **Orphan pruning** — every page created by mk2conf is stamped with a hidden `mk2conf-managed` property. Pass `--prune` to automatically delete managed pages that have been removed from `nav:`. Manually-created Confluence pages are never deleted.
+
+#### Orphan pruning
+
+```bash
+mk2conf publish --prune
+```
+
+After each publish run, `--prune` fetches all descendants of the configured `parent_page_id`, diffs them against the pages just published, and deletes any managed orphans — i.e. pages that carry the `mk2conf-managed` stamp but are no longer in the MkDocs nav.
+
+> **Safety:** Only pages stamped by mk2conf are eligible for deletion. Any page created directly in Confluence will never be touched, even if it sits inside the managed hierarchy.
+>
+> **Partial runs:** `--prune` is silently ignored when `--page` or `--section` is used, because a partial publish would only cover a subset of the nav and would incorrectly identify out-of-scope pages as orphans.
 
 #### Mermaid rendering
 
@@ -283,7 +298,7 @@ Any unrecognised block is preserved as a visible `warning` macro — no content
 
 ## Roadmap
 
-- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+- [x] **Delete orphaned pages** — `--prune` detects and removes managed Confluence pages that have been removed from `nav:`. Manually-created pages are never deleted.
 
 ---
 

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.5.28"
+version = "0.6.1"
 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" }
@@ -88,4 +88,11 @@ exclude_lines = [
   "pragma: no cover",
   "if TYPE_CHECKING:",
   "raise NotImplementedError",
-]
+]
+
+[dependency-groups]
+dev = [
+    "pip-audit>=2.10.0",
+    "radon>=6.0.1",
+    "vulture>=2.16",
+]

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.5.28
+Version: 0.6.1
 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
@@ -41,6 +41,7 @@ Dynamic: license-file
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
+[![Downloads](https://img.shields.io/pypi/dm/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)
 [![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
 [![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
 [![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
@@ -133,7 +134,7 @@ The `--html` flag renders Confluence macros as visual HTML panels so you can rev
 Compile all pages listed in `nav:` and publish them to Confluence Cloud.
 
 ```
-mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE] [--prune]
 ```
 
 | Flag | Default | Description |
@@ -143,6 +144,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
 | `--dry-run` | off | Print the publish plan without making any API calls |
 | `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+| `--prune` | off | Delete managed Confluence pages no longer in `nav:` (see [Orphan pruning](#orphan-pruning)) |
 
 #### Configuration
 
@@ -171,6 +173,19 @@ The API token is read from (in priority order):
 - Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
 - All locally linked assets are uploaded as Confluence page attachments automatically.
 - **Smart update detection** — before calling the Confluence update API, mk2conf compares a `sha256` hash of the compiled output against the hash stored from the previous run (kept as a hidden Confluence page property `mk2conf-content-hash`). Pages whose content has not changed are skipped entirely — no version bump, no watcher notification.
+- **Orphan pruning** — every page created by mk2conf is stamped with a hidden `mk2conf-managed` property. Pass `--prune` to automatically delete managed pages that have been removed from `nav:`. Manually-created Confluence pages are never deleted.
+
+#### Orphan pruning
+
+```bash
+mk2conf publish --prune
+```
+
+After each publish run, `--prune` fetches all descendants of the configured `parent_page_id`, diffs them against the pages just published, and deletes any managed orphans — i.e. pages that carry the `mk2conf-managed` stamp but are no longer in the MkDocs nav.
+
+> **Safety:** Only pages stamped by mk2conf are eligible for deletion. Any page created directly in Confluence will never be touched, even if it sits inside the managed hierarchy.
+>
+> **Partial runs:** `--prune` is silently ignored when `--page` or `--section` is used, because a partial publish would only cover a subset of the nav and would incorrectly identify out-of-scope pages as orphans.
 
 #### Mermaid rendering
 
@@ -321,7 +336,7 @@ Any unrecognised block is preserved as a visible `warning` macro — no content
 
 ## Roadmap
 
-- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+- [x] **Delete orphaned pages** — `--prune` detects and removes managed Confluence pages that have been removed from `nav:`. Manually-created pages are never deleted.
 
 ---
 

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/src/mkdocs_to_confluence/cli.py

@@ -115,6 +115,15 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Write a JSON publish report to FILE after the run.",
     )
+    publish.add_argument(
+        "--prune",
+        action="store_true",
+        help=(
+            "Delete managed Confluence pages that are no longer in the MkDocs nav. "
+            "Only pages stamped by mk2conf are eligible — manually-created pages are never deleted. "
+            "Ignored when --page or --section is used."
+        ),
+    )
 
     return parser
 
@@ -308,10 +317,14 @@ def _cmd_publish(args: argparse.Namespace) -> None:
                 )
                 sys.exit(1)
             plan = plan_publish(nav_nodes, client, config, conf_config, space_id=space_id)
+            # --prune is silently disabled for partial publishes (--page / --section)
+            # because published_ids would only cover the subset, not the full nav.
+            partial = bool(getattr(args, "page", None) or getattr(args, "section", None))
             report = execute_publish(
                 plan, client, dry_run=False, space_id=space_id,
                 docs_dir=config.docs_dir, full_width=conf_config.full_width,
                 root_page_id=conf_config.parent_page_id,
+                prune=getattr(args, "prune", False) and not partial,
             )
     except ConfluenceError as exc:
         print(f"error: {exc}", file=sys.stderr)

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/src/mkdocs_to_confluence/loader/config.py

@@ -107,7 +107,7 @@ def _make_env_loader() -> type[yaml.SafeLoader]:
 
     # Catch-all: any other unknown tag (e.g. !!python/name:... used by
     # MkDocs Material) is silently ignored — we only care about nav/site_name.
-    def _ignore(loader: yaml.SafeLoader, tag_suffix: str, node: yaml.Node) -> None:
+    def _ignore(loader: yaml.SafeLoader, _tag_suffix: str, node: yaml.Node) -> None:
         return None
 
     _Loader.add_multi_constructor("", _ignore)  # type: ignore[no-untyped-call]

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/src/mkdocs_to_confluence/loader/nav.py

@@ -39,7 +39,7 @@ class NavNode:
         return self.docs_path is not None
 
 
-def resolve_nav(config: MkDocsConfig, mkdocs_root: Path | None = None) -> list[NavNode]:
+def resolve_nav(config: MkDocsConfig) -> list[NavNode]:
     """Resolve *config.nav* into a list of top-level :class:`NavNode` objects.
 
     When ``config.nav`` is ``None`` (e.g. projects using ``awesome-pages`` or
@@ -48,8 +48,6 @@ def resolve_nav(config: MkDocsConfig, mkdocs_root: Path | None = None) -> list[N
 
     Args:
         config: Parsed :class:`~mkdocs_to_confluence.loader.config.MkDocsConfig`.
-        mkdocs_root: Directory containing ``mkdocs.yml``.  Used only to compute
-            ``docs_dir`` when it is not already absolute; defaults to CWD.
 
     Returns:
         List of top-level :class:`NavNode` instances.

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/src/mkdocs_to_confluence/preprocess/includes.py

@@ -290,7 +290,7 @@ def _resolve_include_path(rel_path: str, source_path: Path, docs_dir: Path) -> P
     """
     for base in (docs_dir, source_path.parent):
         candidate = (base / rel_path).resolve()
-        if candidate.is_file():
+        if candidate.is_file() and candidate.is_relative_to(base.resolve()):
             return candidate
     return None
 

{mkdocs2confluence-0.5.28 → mkdocs2confluence-0.6.1}/src/mkdocs_to_confluence/publisher/client.py

@@ -9,12 +9,20 @@ from __future__ import annotations
 import base64
 from pathlib import Path
 from typing import Any, cast
+from urllib.parse import parse_qs, urlparse
 
 import httpx
 
 from mkdocs_to_confluence.loader.config import ConfluenceConfig
 
 
+def _extract_cursor(next_url: str) -> str:
+    """Extract the ``cursor`` query parameter from a pagination ``next`` URL."""
+    qs = parse_qs(urlparse(next_url).query)
+    cursors = qs.get("cursor", [])
+    return cursors[0] if cursors else ""
+
+
 class ConfluenceError(RuntimeError):
     """Raised when the Confluence API returns an unexpected response."""
 
@@ -409,3 +417,59 @@ class ConfluenceClient:
             headers={"X-Atlassian-Token": "no-check"},
         )
         self._raise_for_status(resp, f"upload_attachment({filename!r})")
+
+    # ── Orphan detection ───────────────────────────────────────────────────────
+
+    def stamp_managed(self, page_id: str) -> None:
+        """Mark *page_id* as managed by mk2conf via a v2 content property.
+
+        The property ``mk2conf-managed`` is set to ``true`` on first publish and
+        never updated.  It is used by :meth:`is_managed` to distinguish pages
+        created by mk2conf from manually-created Confluence pages.
+
+        Errors are swallowed — this is a best-effort stamp and must never block
+        a publish.
+        """
+        url = self._v2(f"/pages/{page_id}/properties/mk2conf-managed")
+        get_resp = self._http.get(url)
+        if get_resp.status_code == 200:
+            return  # already stamped
+        self._http.post(
+            self._v2(f"/pages/{page_id}/properties"),
+            json={"key": "mk2conf-managed", "value": True},
+        )
+
+    def get_descendant_ids(self, page_id: str) -> list[str]:
+        """Return all descendant page IDs under *page_id* at all depths.
+
+        Uses ``GET /wiki/api/v2/pages/{id}/descendants?depth=all``.
+        Paginates automatically via cursor.  Returns page IDs only — callers
+        that need to filter by managed status use :meth:`is_managed`.
+        """
+        ids: list[str] = []
+        url = self._v2(f"/pages/{page_id}/descendants")
+        params: dict[str, str | int] = {"depth": "all", "limit": 250}
+        while True:
+            resp = self._http.get(url, params=params)
+            self._raise_for_status(resp, f"get_descendant_ids({page_id!r})")
+            data = resp.json()
+            for item in data.get("results", []):
+                if item.get("type") == "page":
+                    ids.append(str(item["id"]))
+            next_url = data.get("_links", {}).get("next")
+            if not next_url:
+                break
+            # next_url is an absolute path — extract cursor and re-request
+            url = self._v2(f"/pages/{page_id}/descendants")
+            params = {"depth": "all", "limit": 250, "cursor": _extract_cursor(next_url)}
+        return ids
+
+    def is_managed(self, page_id: str) -> bool:
+        """Return ``True`` if *page_id* has the ``mk2conf-managed`` property."""
+        resp = self._http.get(self._v2(f"/pages/{page_id}/properties/mk2conf-managed"))
+        return resp.status_code == 200
+
+    def delete_page(self, page_id: str) -> None:
+        """Permanently delete *page_id* from Confluence."""
+        resp = self._http.delete(self._v2(f"/pages/{page_id}"))
+        self._raise_for_status(resp, f"delete_page({page_id!r})")