mkdocs2confluence 0.6.2__tar.gz → 0.6.4__tar.gz

{mkdocs2confluence-0.6.2/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.6.2
+Version: 0.6.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
@@ -88,6 +88,8 @@ cd mkdocs2confluence
 pip install -e ".[dev]"
 ```
 
+> **Package name vs. command name** — This follows the same convention used by many popular CLI tools (e.g. `pip install httpie` → `http` command). The PyPI package is `mkdocs2confluence` (descriptive, easy to find), and the CLI command is `mk2conf` (short, fast to type). Install once, run everywhere as `mk2conf`.
+
 ---
 
 ## Quick start
@@ -112,7 +114,7 @@ CONFLUENCE_API_TOKEN=your_token mk2conf publish --config mkdocs.yml
 
 ### `mk2conf preview`
 
-Compile a single page and inspect the output — no network connection required.
+Compile a single page and inspect the output — no Confluence API calls required. Mermaid diagrams are rendered via Kroki unless `mermaid_render: none` is set.
 
 ```
 mk2conf preview [--config PATH] --page PATH [--out FILE] [--html]
@@ -142,7 +144,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
 | `--page PATH` | *(all nav pages)* | Publish a single page only |
 | `--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 |
+| `--dry-run` | off | Print the publish plan without making any Confluence API calls (Mermaid diagrams are still rendered via Kroki unless `mermaid_render: none` is set) |
 | `--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)) |
 
@@ -172,7 +174,7 @@ The API token is read from (in priority order):
 - Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
 - 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.
+- **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. As a side effect, Confluence's built-in version history becomes a meaningful audit trail: every version represents a real content change, each stamped *"Updated by mk2conf"* so automated publishes are clearly distinguishable from manual edits. You can diff any two versions directly inside Confluence, with inline highlighting showing exactly which paragraphs, headings, or code blocks changed.
 - **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
@@ -346,7 +348,7 @@ See [Setup.md](Setup.md) for environment setup.
 
 ```bash
 pytest              # run tests
-ruff check src      # lint
+ruff check src tests  # lint
 mypy src            # type-check
 bandit -r src -ll   # security scan
 ```

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.4}/README.md

@@ -50,6 +50,8 @@ cd mkdocs2confluence
 pip install -e ".[dev]"
 ```
 
+> **Package name vs. command name** — This follows the same convention used by many popular CLI tools (e.g. `pip install httpie` → `http` command). The PyPI package is `mkdocs2confluence` (descriptive, easy to find), and the CLI command is `mk2conf` (short, fast to type). Install once, run everywhere as `mk2conf`.
+
 ---
 
 ## Quick start
@@ -74,7 +76,7 @@ CONFLUENCE_API_TOKEN=your_token mk2conf publish --config mkdocs.yml
 
 ### `mk2conf preview`
 
-Compile a single page and inspect the output — no network connection required.
+Compile a single page and inspect the output — no Confluence API calls required. Mermaid diagrams are rendered via Kroki unless `mermaid_render: none` is set.
 
 ```
 mk2conf preview [--config PATH] --page PATH [--out FILE] [--html]
@@ -104,7 +106,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
 | `--page PATH` | *(all nav pages)* | Publish a single page only |
 | `--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 |
+| `--dry-run` | off | Print the publish plan without making any Confluence API calls (Mermaid diagrams are still rendered via Kroki unless `mermaid_render: none` is set) |
 | `--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)) |
 
@@ -134,7 +136,7 @@ The API token is read from (in priority order):
 - Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
 - 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.
+- **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. As a side effect, Confluence's built-in version history becomes a meaningful audit trail: every version represents a real content change, each stamped *"Updated by mk2conf"* so automated publishes are clearly distinguishable from manual edits. You can diff any two versions directly inside Confluence, with inline highlighting showing exactly which paragraphs, headings, or code blocks changed.
 - **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
@@ -308,7 +310,7 @@ See [Setup.md](Setup.md) for environment setup.
 
 ```bash
 pytest              # run tests
-ruff check src      # lint
+ruff check src tests  # lint
 mypy src            # type-check
 bandit -r src -ll   # security scan
 ```

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.6.2"
+version = "0.6.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.6.2 → mkdocs2confluence-0.6.4/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.6.2
+Version: 0.6.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
@@ -88,6 +88,8 @@ cd mkdocs2confluence
 pip install -e ".[dev]"
 ```
 
+> **Package name vs. command name** — This follows the same convention used by many popular CLI tools (e.g. `pip install httpie` → `http` command). The PyPI package is `mkdocs2confluence` (descriptive, easy to find), and the CLI command is `mk2conf` (short, fast to type). Install once, run everywhere as `mk2conf`.
+
 ---
 
 ## Quick start
@@ -112,7 +114,7 @@ CONFLUENCE_API_TOKEN=your_token mk2conf publish --config mkdocs.yml
 
 ### `mk2conf preview`
 
-Compile a single page and inspect the output — no network connection required.
+Compile a single page and inspect the output — no Confluence API calls required. Mermaid diagrams are rendered via Kroki unless `mermaid_render: none` is set.
 
 ```
 mk2conf preview [--config PATH] --page PATH [--out FILE] [--html]
@@ -142,7 +144,7 @@ mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--re
 | `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
 | `--page PATH` | *(all nav pages)* | Publish a single page only |
 | `--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 |
+| `--dry-run` | off | Print the publish plan without making any Confluence API calls (Mermaid diagrams are still rendered via Kroki unless `mermaid_render: none` is set) |
 | `--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)) |
 
@@ -172,7 +174,7 @@ The API token is read from (in priority order):
 - Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
 - 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.
+- **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. As a side effect, Confluence's built-in version history becomes a meaningful audit trail: every version represents a real content change, each stamped *"Updated by mk2conf"* so automated publishes are clearly distinguishable from manual edits. You can diff any two versions directly inside Confluence, with inline highlighting showing exactly which paragraphs, headings, or code blocks changed.
 - **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
@@ -346,7 +348,7 @@ See [Setup.md](Setup.md) for environment setup.
 
 ```bash
 pytest              # run tests
-ruff check src      # lint
+ruff check src tests  # lint
 mypy src            # type-check
 bandit -r src -ll   # security scan
 ```

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.4}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -42,6 +42,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_cli.py
 tests/test_editlink.py
 tests/test_emitter.py
 tests/test_extra_css.py

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.4}/src/mkdocs_to_confluence/cli.py

@@ -33,7 +33,17 @@ def _build_parser() -> argparse.ArgumentParser:
     # --- preview ---
     preview = sub.add_parser(
         "preview",
-        help="Compile a single page and print Confluence XHTML to stdout (no network).",
+        help="Compile a page (or whole section) and inspect the output — no Confluence API calls.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  mk2conf preview --page index.md\n"
+            "  mk2conf preview --page guide/setup.md --html --out /tmp/setup.html\n"
+            "  mk2conf preview --section Guide\n"
+            "\n"
+            "  Either --page or --section is required.\n"
+            "  Mermaid diagrams are rendered via Kroki unless 'mermaid_render: none' is set.\n"
+        ),
     )
     preview.add_argument(
         "--config",
@@ -47,7 +57,7 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help=(
             "Relative path to the markdown file to compile. "
-            "Omit when --section is given to preview the whole section."
+            "Required unless --section is given."
         ),
     )
     preview.add_argument(
@@ -65,7 +75,17 @@ def _build_parser() -> argparse.ArgumentParser:
         "--section",
         metavar="NAME",
         default=None,
-        help="Restrict link map to a nav section (slash-separated path, e.g. 'Guide/Setup').",
+        help=(
+            "Nav section to preview (slash-separated path, e.g. 'Guide' or 'Guide/Setup'). "
+            "Without --page, renders all pages in the section as a browseable HTML index."
+        ),
+    )
+
+    preview.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress per-item progress output; only the final summary and warnings are shown.",
     )
 
     # --- publish ---
@@ -125,6 +145,13 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    publish.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress per-item progress output; only the final summary and warnings are shown.",
+    )
+
     return parser
 
 
@@ -136,12 +163,17 @@ def main(argv: list[str] | None = None) -> None:
         parser.print_help()
         sys.exit(0)
 
-    print(f"mk2conf {__version__}")
+    if sys.stdout.isatty():
+        print(f"mk2conf {__version__}")
 
-    if args.command == "preview":
-        _cmd_preview(args)
-    elif args.command == "publish":
-        _cmd_publish(args)
+    try:
+        if args.command == "preview":
+            _cmd_preview(args)
+        elif args.command == "publish":
+            _cmd_publish(args)
+    except (ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
 
 
 def _parse_out_path(out_arg: str | None) -> tuple[Path, str]:
@@ -202,7 +234,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, _attachments, _labels = compile_page(node, config, link_map)
+                xhtml, _attachments, _labels = compile_page(node, config, link_map, quiet=args.quiet)
             except PageLoadError as exc:
                 print(f"  warning: skipping '{node.title}': {exc}", file=sys.stderr)
                 continue
@@ -227,7 +259,7 @@ def _cmd_preview(args: argparse.Namespace) -> None:
 
     try:
         link_map = build_link_map(nodes)
-        xhtml, _attachments, _labels = compile_page(page_node, config, link_map)
+        xhtml, _attachments, _labels = compile_page(page_node, config, link_map, quiet=args.quiet)
     except PageLoadError as exc:
         print(f"error: {exc}", file=sys.stderr)
         sys.exit(1)
@@ -316,7 +348,7 @@ def _cmd_publish(args: argparse.Namespace) -> None:
                     file=sys.stderr,
                 )
                 sys.exit(1)
-            plan = plan_publish(nav_nodes, client, config, conf_config, space_id=space_id)
+            plan = plan_publish(nav_nodes, client, config, conf_config, space_id=space_id, quiet=args.quiet)
             # --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))
@@ -325,6 +357,7 @@ def _cmd_publish(args: argparse.Namespace) -> None:
                 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,
+                quiet=args.quiet,
             )
     except ConfluenceError as exc:
         print(f"error: {exc}", file=sys.stderr)

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.4}/src/mkdocs_to_confluence/loader/nav.py

@@ -82,19 +82,26 @@ def _discover(docs_dir: Path, nav_file: str) -> list[NavNode]:
 
 
 def _read_nav_file(directory: Path, nav_file: str) -> list[Any] | None:
-    """Return the nav list from *directory*/<nav_file>, or None if absent/unreadable."""
+    """Return the nav list from *directory*/<nav_file>, or None if absent.
+
+    Raises ValueError if the file exists but cannot be parsed or has an
+    unexpected format — a present-but-broken nav file is a configuration
+    error, not a reason to silently fall back to full discovery.
+    """
     path = directory / nav_file
     if not path.exists():
         return None
     try:
         data = yaml.safe_load(path.read_text(encoding="utf-8"))
-        if isinstance(data, dict) and isinstance(data.get("nav"), list):
-            return cast(list[Any], data["nav"])
-        if isinstance(data, list):
-            return data
-    except Exception:
-        pass
-    return None
+    except Exception as exc:
+        raise ValueError(f"Could not parse nav file {path}: {exc}") from exc
+    if isinstance(data, dict) and isinstance(data.get("nav"), list):
+        return cast(list[Any], data["nav"])
+    if isinstance(data, list):
+        return data
+    raise ValueError(
+        f"Nav file {path} has unexpected format (expected a list or a dict with a 'nav' key, got {type(data).__name__})"
+    )
 
 
 def _traverse_nav_dir(

{mkdocs2confluence-0.6.2 → mkdocs2confluence-0.6.4}/src/mkdocs_to_confluence/publisher/pipeline.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import hashlib
 import re
+import sys
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -134,6 +135,8 @@ def compile_page(
     node: NavNode,
     config: MkDocsConfig,
     link_map: dict[str, str] | None = None,
+    *,
+    quiet: bool = False,
 ) -> tuple[str, list[Path], tuple[str, ...]]:
     """Run the full compile pipeline for one page.
 
@@ -174,7 +177,7 @@ def compile_page(
             mermaid_render[len("kroki:"):] if mermaid_render.startswith("kroki:")
             else DEFAULT_KROKI_URL
         )
-        ir_nodes, mermaid_attachments = render_mermaid_diagrams(ir_nodes, kroki_url)
+        ir_nodes, mermaid_attachments = render_mermaid_diagrams(ir_nodes, kroki_url, quiet=quiet)
         attachments = attachments + mermaid_attachments
     effective_link_map = link_map if link_map is not None else {}
     if node.docs_path:
@@ -220,6 +223,7 @@ def plan_publish(
     conf_config: ConfluenceConfig,
     *,
     space_id: str,
+    quiet: bool = False,
 ) -> list[PageAction]:
     """Build a publish plan for the entire nav tree.
 
@@ -229,8 +233,9 @@ def plan_publish(
     """
     actions: list[PageAction] = []
     link_map = build_link_map(nav_nodes)
-    print("Planning...")
-    _plan_nodes(nav_nodes, client, config, space_id, conf_config.parent_page_id, False, actions, link_map)
+    if not quiet:
+        print("Planning...")
+    _plan_nodes(nav_nodes, client, config, space_id, conf_config.parent_page_id, False, actions, link_map, quiet=quiet)
     return actions
 
 
@@ -243,6 +248,8 @@ def _plan_nodes(
     parent_is_folder: bool,
     actions: list[PageAction],
     link_map: dict[str, str] | None = None,
+    *,
+    quiet: bool = False,
 ) -> None:
     for node in nodes:
         # Strip icon shortcodes from titles — nav titles bypass the body
@@ -261,13 +268,15 @@ def _plan_nodes(
                     except OSError:
                         pass
                 if ready is not False and index_child.source_path is not None:
-                    print(f"  compiling  '{clean_title}'  (section index)")
+                    if not quiet:
+                        print(f"  compiling  '{clean_title}'  (section index)")
                     try:
-                        xhtml, attachments, labels = compile_page(index_child, config, link_map)
+                        xhtml, attachments, labels = compile_page(index_child, config, link_map, quiet=quiet)
                         existing = client.find_page(space_id, clean_title)
                         xhtml_h = _xhtml_hash(xhtml)
                         if existing is not None and client.get_content_hash(str(existing["id"])) == xhtml_h:
-                            print(f"  unchanged  '{clean_title}'  (content unchanged)")
+                            if not quiet:
+                                print(f"  unchanged  '{clean_title}'  (content unchanged)")
                             actions.append(PageAction(
                                 node=node,
                                 title=clean_title,
@@ -278,7 +287,8 @@ def _plan_nodes(
                             ))
                             non_index = [c for c in node.children if c is not index_child]
                             _plan_nodes(
-                                non_index, client, config, space_id, str(existing["id"]), False, actions, link_map
+                                non_index, client, config, space_id,
+                                str(existing["id"]), False, actions, link_map, quiet=quiet
                             )
                             continue
                         page_action = PageAction(
@@ -301,16 +311,18 @@ def _plan_nodes(
                         # Recurse remaining children — index.md is already consumed.
                         non_index = [c for c in node.children if c is not index_child]
                         _plan_nodes(
-                            non_index, client, config, space_id, None, False, actions, link_map
+                            non_index, client, config, space_id, None, False, actions, link_map, quiet=quiet
                         )
                         continue
                     except (PageLoadError, OSError) as exc:
                         print(
-                            f"  warning    '{clean_title}'  index.md error ({exc}),"
-                            " falling back to folder"
+                            f"  [warn] '{clean_title}'  index.md load error ({exc}),"
+                            " falling back to folder",
+                            file=sys.stderr,
                         )
 
-            print(f"  compiling  '{clean_title}'  (folder)")
+            if not quiet:
+                print(f"  compiling  '{clean_title}'  (folder)")
             # Folder find-or-create is deferred to execute_publish once the
             # parent folder ID is known (nested folders don't have a parent ID
             # yet at plan time).
@@ -327,7 +339,7 @@ def _plan_nodes(
             actions.append(page_action)
             # Children will be placed under this folder's ID (resolved at execute)
             _plan_nodes(
-                list(node.children), client, config, space_id, None, True, actions, link_map
+                list(node.children), client, config, space_id, None, True, actions, link_map, quiet=quiet
             )
         else:
             # Page node — read raw to check ready flag
@@ -340,7 +352,8 @@ def _plan_nodes(
                     pass
 
             if ready is False:
-                print(f"  skipping   '{clean_title}'  (ready: false)")
+                if not quiet:
+                    print(f"  skipping   '{clean_title}'  (ready: false)")
                 actions.append(
                     PageAction(
                         node=node,
@@ -351,11 +364,13 @@ def _plan_nodes(
                 )
                 continue
 
-            print(f"  compiling  '{clean_title}'")
+            if not quiet:
+                print(f"  compiling  '{clean_title}'")
             try:
-                xhtml, attachments, labels = compile_page(node, config, link_map)
+                xhtml, attachments, labels = compile_page(node, config, link_map, quiet=quiet)
             except (PageLoadError, OSError) as exc:
-                print(f"  skipping   '{clean_title}'  (error: {exc})")
+                if not quiet:
+                    print(f"  skipping   '{clean_title}'  (error: {exc})")
                 actions.append(
                     PageAction(
                         node=node,
@@ -369,7 +384,8 @@ def _plan_nodes(
             existing = client.find_page(space_id, clean_title)
             xhtml_h = _xhtml_hash(xhtml)
             if existing is not None and client.get_content_hash(str(existing["id"])) == xhtml_h:
-                print(f"  unchanged  '{clean_title}'  (content unchanged)")
+                if not quiet:
+                    print(f"  unchanged  '{clean_title}'  (content unchanged)")
                 actions.append(
                     PageAction(
                         node=node,
@@ -406,6 +422,8 @@ def _upload_assets(
     attachments: list[Path],
     docs_dir: Path,
     client: ConfluenceClient,
+    *,
+    quiet: bool = False,
 ) -> tuple[int, int, list[tuple[str, str]]]:
     """Upload attachments for one page **sequentially**.
 
@@ -442,13 +460,15 @@ def _upload_assets(
                     path.stat().st_mtime, tz=timezone.utc
                 )
                 if local_mtime <= confluence_ts:
-                    print(f"        skipping   {name} (unchanged)")
+                    if not quiet:
+                        print(f"        skipping   {name} (unchanged)")
                     skipped += 1
                     continue
             except (KeyError, ValueError, OSError):
                 pass  # can't compare — fall through to upload
 
-        print(f"        uploading  {name}")
+        if not quiet:
+            print(f"        uploading  {name}")
         try:
             client.upload_attachment(page_id, path, name, existing)
             uploaded += 1
@@ -464,6 +484,8 @@ def _execute_folder_action(
     space_id: str,
     root_page_id: str | None,
     report: PublishReport,
+    *,
+    quiet: bool = False,
 ) -> None:
     """Handle folder create/find for a single folder action."""
     if action.page_id is not None:
@@ -482,8 +504,9 @@ def _execute_folder_action(
                 )
             except Exception as find_exc:
                 print(
-                    f"         [warn] find_folder_under failed "
-                    f"(parent_id={action.parent_id}): {find_exc}"
+                    f"  [warn] find_folder_under failed "
+                    f"(parent_id={action.parent_id}): {find_exc}",
+                    file=sys.stderr,
                 )
         if existing_folder is not None:
             action.page_id = str(existing_folder["id"])
@@ -497,11 +520,12 @@ def _execute_folder_action(
             )
             action.page_id = str(folder["id"])
             report.created += 1
-            print(
-                f"         folder id={action.page_id}"
-                f"  parent_id={action.parent_id}"
-                f"  parent_is_folder={action.parent_is_folder}"
-            )
+            if not quiet:
+                print(
+                    f"         folder id={action.page_id}"
+                    f"  parent_id={action.parent_id}"
+                    f"  parent_is_folder={action.parent_is_folder}"
+                )
     else:
         # Parent is a dynamically-created page (e.g. a section-index page).
         # Confluence folders cannot be nested under pages — use a stub page.
@@ -563,8 +587,9 @@ def _execute_page_action(
             if not is_stale:
                 raise
             print(
-                f"         [warn] update failed ({err[:80].strip()}) —"
-                " stale page_id; falling back to create"
+                f"  [warn] update failed ({err[:80].strip()}) —"
+                " stale page_id; falling back to create",
+                file=sys.stderr,
             )
             action.page_id = None
             page = client.create_page(
@@ -602,6 +627,7 @@ def _post_process_action(
     full_width: bool,
     docs_dir: Path,
     report: PublishReport,
+    quiet: bool = False,
 ) -> None:
     """Run all non-fatal post-create/update work for a single action."""
     # Store content hash after create/update so the next run can skip unchanged pages.
@@ -628,7 +654,7 @@ def _post_process_action(
     # Upload assets — skip files whose mtime is not newer than Confluence.
     if action.page_id and action.attachments:
         uploaded, asset_skipped, asset_errors = _upload_assets(
-            action.page_id, action.attachments, docs_dir, client
+            action.page_id, action.attachments, docs_dir, client, quiet=quiet
         )
         report.assets_uploaded += uploaded
         report.assets_skipped += asset_skipped
@@ -646,6 +672,7 @@ def execute_publish(
     full_width: bool = True,
     root_page_id: str | None = None,
     prune: bool = False,
+    quiet: bool = False,
 ) -> PublishReport:
     """Execute the publish plan.
 
@@ -674,7 +701,8 @@ def execute_publish(
 
     active = [a for a in plan if a.action != "skip"]
     total = len(active)
-    print(f"\nPublishing {total} page(s)...")
+    if not quiet:
+        print(f"\nPublishing {total} page(s)...")
     counter = 0
 
     for action in plan:
@@ -683,11 +711,12 @@ def execute_publish(
             continue
 
         counter += 1
-        print(f"  [{counter}/{total}] {action.action:<6}  '{action.title}'")
+        if not quiet:
+            print(f"  [{counter}/{total}] {action.action:<6}  '{action.title}'")
 
         try:
             if action.is_folder:
-                _execute_folder_action(action, client, space_id, root_page_id, report)
+                _execute_folder_action(action, client, space_id, root_page_id, report, quiet=quiet)
             else:
                 _execute_page_action(action, client, space_id, report)
         except Exception as exc:
@@ -700,11 +729,11 @@ def execute_publish(
         if action.node.is_section and action.page_id:
             _wire_children(action, action_by_node)
 
-        _post_process_action(action, client, full_width=full_width, docs_dir=docs_dir, report=report)
+        _post_process_action(action, client, full_width=full_width, docs_dir=docs_dir, report=report, quiet=quiet)
 
     if prune and root_page_id:
         published_ids = {a.page_id for a in plan if a.page_id}
-        _prune_orphans(client, root_page_id, published_ids, report)
+        _prune_orphans(client, root_page_id, published_ids, report, quiet=quiet)
 
     return report
 
@@ -714,6 +743,8 @@ def _prune_orphans(
     root_page_id: str,
     published_ids: set[str],
     report: PublishReport,
+    *,
+    quiet: bool = False,
 ) -> None:
     """Delete managed descendant pages that are no longer in the publish plan.
 
@@ -723,20 +754,22 @@ def _prune_orphans(
     try:
         all_descendants = client.get_descendant_ids(root_page_id)
     except Exception as exc:
-        print(f"  [warn] prune: could not fetch descendants — {exc}")
+        print(f"  [warn] prune: could not fetch descendants — {exc}", file=sys.stderr)
         return
 
     orphan_candidates = [pid for pid in all_descendants if pid not in published_ids]
     if not orphan_candidates:
         return
 
-    print(f"\nPruning: checking {len(orphan_candidates)} orphan candidate(s)...")
+    if not quiet:
+        print(f"\nPruning: checking {len(orphan_candidates)} orphan candidate(s)...")
     for page_id in orphan_candidates:
         try:
             if not client.is_managed(page_id):
                 continue
             client.delete_page(page_id)
             report.pruned += 1
-            print(f"  deleted orphan page {page_id}")
+            if not quiet:
+                print(f"  deleted orphan page {page_id}")
         except Exception as exc:
-            print(f"  [warn] prune: failed to delete page {page_id} — {exc}")
+            print(f"  [warn] prune: failed to delete page {page_id} — {exc}", file=sys.stderr)