mkdocs2confluence 0.12.0__tar.gz → 0.13.0__tar.gz

{mkdocs2confluence-0.12.0/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.12.0
+Version: 0.13.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
@@ -25,6 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: httpx>=0.27
+Requires-Dist: idna>=3.15
 Requires-Dist: tinycss2>=1.5.1
 Provides-Extra: pdf
 Requires-Dist: weasyprint>=60.0; extra == "pdf"
@@ -152,10 +153,26 @@ confluence:
   parent_page_id: "123456"           # optional root page
   mermaid_render: kroki              # "kroki" (default) | "kroki:https://your-kroki" | "none"
   full_width: true                   # default: true
+  changelog: CHANGELOG.md           # optional: publish as a top-level "What's New" page
 ```
 
 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
+
+Set `changelog:` to a Markdown file path (relative to `docs_dir`) to have mk2conf publish it as a permanent top-level page on every full `mk2conf publish` run. The page title comes from YAML front matter `title:`; it defaults to `"What's New"` if absent.
+
+```yaml
+confluence:
+  changelog: CHANGELOG.md   # relative to docs_dir
+```
+
+- The page does **not** need to appear in `nav:` — it is always placed at the top level of the space (or under `parent_page_id` if set).
+- If it also appears in `nav:`, it is published once; no duplication.
+- `--prune` never deletes it — it is a pinned page, not a nav-derived page.
+- Partial runs (`--page` / `--section`) skip the changelog page, consistent with other publish behaviour.
+- Omit the key, or set it to an empty string, to disable the feature entirely.
+
 **Your first publish:**
 
 ```bash
@@ -181,7 +198,13 @@ mk2conf publish                                 # go live
 
 ![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)
 
-Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**. The plan phase makes all API read calls; the execute phase makes all write calls in nav order so parent pages always exist before their children.
+Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.
+
+The publisher is split into two phases:
+- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.
+- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.
+
+`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.
 
 ---
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0}/README.md

@@ -111,10 +111,26 @@ confluence:
   parent_page_id: "123456"           # optional root page
   mermaid_render: kroki              # "kroki" (default) | "kroki:https://your-kroki" | "none"
   full_width: true                   # default: true
+  changelog: CHANGELOG.md           # optional: publish as a top-level "What's New" page
 ```
 
 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
+
+Set `changelog:` to a Markdown file path (relative to `docs_dir`) to have mk2conf publish it as a permanent top-level page on every full `mk2conf publish` run. The page title comes from YAML front matter `title:`; it defaults to `"What's New"` if absent.
+
+```yaml
+confluence:
+  changelog: CHANGELOG.md   # relative to docs_dir
+```
+
+- The page does **not** need to appear in `nav:` — it is always placed at the top level of the space (or under `parent_page_id` if set).
+- If it also appears in `nav:`, it is published once; no duplication.
+- `--prune` never deletes it — it is a pinned page, not a nav-derived page.
+- Partial runs (`--page` / `--section`) skip the changelog page, consistent with other publish behaviour.
+- Omit the key, or set it to an empty string, to disable the feature entirely.
+
 **Your first publish:**
 
 ```bash
@@ -140,7 +156,13 @@ mk2conf publish                                 # go live
 
 ![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)
 
-Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**. The plan phase makes all API read calls; the execute phase makes all write calls in nav order so parent pages always exist before their children.
+Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.
+
+The publisher is split into two phases:
+- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.
+- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.
+
+`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.
 
 ---
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.12.0"
+version = "0.13.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" }
@@ -32,6 +32,7 @@ classifiers = [
 dependencies = [
   "PyYAML>=6.0.3",
   "httpx>=0.27",
+  "idna>=3.15",
   "tinycss2>=1.5.1",
 ]
 
@@ -66,6 +67,9 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"mkdocs_to_confluence" = ["skills/**/*.md"]
+
 [tool.ruff]
 line-length = 120
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.12.0
+Version: 0.13.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
@@ -25,6 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: httpx>=0.27
+Requires-Dist: idna>=3.15
 Requires-Dist: tinycss2>=1.5.1
 Provides-Extra: pdf
 Requires-Dist: weasyprint>=60.0; extra == "pdf"
@@ -152,10 +153,26 @@ confluence:
   parent_page_id: "123456"           # optional root page
   mermaid_render: kroki              # "kroki" (default) | "kroki:https://your-kroki" | "none"
   full_width: true                   # default: true
+  changelog: CHANGELOG.md           # optional: publish as a top-level "What's New" page
 ```
 
 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
+
+Set `changelog:` to a Markdown file path (relative to `docs_dir`) to have mk2conf publish it as a permanent top-level page on every full `mk2conf publish` run. The page title comes from YAML front matter `title:`; it defaults to `"What's New"` if absent.
+
+```yaml
+confluence:
+  changelog: CHANGELOG.md   # relative to docs_dir
+```
+
+- The page does **not** need to appear in `nav:` — it is always placed at the top level of the space (or under `parent_page_id` if set).
+- If it also appears in `nav:`, it is published once; no duplication.
+- `--prune` never deletes it — it is a pinned page, not a nav-derived page.
+- Partial runs (`--page` / `--section`) skip the changelog page, consistent with other publish behaviour.
+- Omit the key, or set it to an empty string, to disable the feature entirely.
+
 **Your first publish:**
 
 ```bash
@@ -181,7 +198,13 @@ mk2conf publish                                 # go live
 
 ![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)
 
-Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**. The plan phase makes all API read calls; the execute phase makes all write calls in nav order so parent pages always exist before their children.
+Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.
+
+The publisher is split into two phases:
+- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.
+- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.
+
+`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.
 
 ---
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -9,6 +9,10 @@ src/mkdocs2confluence.egg-info/requires.txt
 src/mkdocs2confluence.egg-info/top_level.txt
 src/mkdocs_to_confluence/__init__.py
 src/mkdocs_to_confluence/cli.py
+src/mkdocs_to_confluence/skill_installer.py
+src/mkdocs_to_confluence/compiler/__init__.py
+src/mkdocs_to_confluence/compiler/models.py
+src/mkdocs_to_confluence/compiler/page.py
 src/mkdocs_to_confluence/emitter/__init__.py
 src/mkdocs_to_confluence/emitter/xhtml.py
 src/mkdocs_to_confluence/ir/__init__.py
@@ -36,9 +40,14 @@ src/mkdocs_to_confluence/preview/__init__.py
 src/mkdocs_to_confluence/preview/render.py
 src/mkdocs_to_confluence/preview/server.py
 src/mkdocs_to_confluence/publisher/__init__.py
+src/mkdocs_to_confluence/publisher/changelog.py
 src/mkdocs_to_confluence/publisher/client.py
+src/mkdocs_to_confluence/publisher/executor.py
 src/mkdocs_to_confluence/publisher/http_retry.py
+src/mkdocs_to_confluence/publisher/models.py
 src/mkdocs_to_confluence/publisher/pipeline.py
+src/mkdocs_to_confluence/publisher/planner.py
+src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md
 src/mkdocs_to_confluence/sync/__init__.py
 src/mkdocs_to_confluence/sync/anchoring.py
 src/mkdocs_to_confluence/sync/command.py
@@ -55,6 +64,8 @@ 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_changelog_config.py
+tests/test_changelog_publish.py
 tests/test_children_macro.py
 tests/test_cli.py
 tests/test_editlink.py
@@ -78,6 +89,7 @@ tests/test_publish_client.py
 tests/test_publish_config.py
 tests/test_publish_pipeline.py
 tests/test_server.py
+tests/test_skill_installer.py
 tests/test_sync_anchoring.py
 tests/test_sync_command.py
 tests/test_sync_comments.py

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0}/src/mkdocs2confluence.egg-info/requires.txt

@@ -1,5 +1,6 @@
 PyYAML>=6.0.3
 httpx>=0.27
+idna>=3.15
 tinycss2>=1.5.1
 
 [dev]

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0}/src/mkdocs_to_confluence/cli.py

@@ -265,6 +265,33 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Suppress progress output.",
     )
 
+    # --- install-skill ---
+    is_ = sub.add_parser(
+        "install-skill",
+        help="Install the mkdocs-changelog AI skill into detected tool directories.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Detected targets (all installed when no --tool given):\n"
+            "  hermes        ~/.hermes/skills/tooling/mkdocs-changelog/SKILL.md\n"
+            "  github-skills .github/skills/tooling/mkdocs-changelog/SKILL.md\n"
+            "  claude        .claude/commands/changelog.md  (frontmatter stripped)\n"
+            "  copilot       .github/instructions/mk2conf-changelog.instructions.md\n"
+            "  cursor        .cursor/rules/mk2conf-changelog.mdc\n"
+            "\n"
+            "Examples:\n"
+            "  mk2conf install-skill\n"
+            "  mk2conf install-skill --tool claude\n"
+            "  mk2conf install-skill --tool hermes\n"
+        ),
+    )
+    is_.add_argument(
+        "--tool",
+        metavar="NAME",
+        default=None,
+        choices=["hermes", "github-skills", "claude", "copilot", "cursor"],
+        help="Install only to a specific tool (hermes, github-skills, claude, copilot, cursor).",
+    )
+
     return parser
 
 
@@ -288,6 +315,8 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_pdf(args)
         elif args.command == "sync-comments":
             _cmd_sync_comments(args)
+        elif args.command == "install-skill":
+            _cmd_install_skill(args)
     except (ValueError, FileNotFoundError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         sys.exit(1)
@@ -499,6 +528,8 @@ def _cmd_publish(args: argparse.Namespace) -> None:
             sys.exit(1)
         nav_nodes = [node]
 
+    partial = bool(getattr(args, "page", None) or getattr(args, "section", None))
+
     if args.dry_run:
         # When a section is given, show what node was matched so the user can
         # verify the section resolved correctly (section vs. leaf page).
@@ -513,8 +544,14 @@ def _cmd_publish(args: argparse.Namespace) -> None:
         print(f"Dry run: would publish {len(pages)} page(s) to {conf_config.base_url}")
         for page in pages:
             print(f"  {page.docs_path} → '{page.title}'")
+        if conf_config.changelog_file and not partial:
+            from mkdocs_to_confluence.publisher.changelog import _extract_title
+            cl_path = config.docs_dir / conf_config.changelog_file
+            cl_title = _extract_title(cl_path) or "What's New"
+            print(f"  {conf_config.changelog_file} → '{cl_title}'  (changelog, top-level)")
         return
 
+    from mkdocs_to_confluence.publisher.changelog import publish_changelog
     from mkdocs_to_confluence.publisher.client import ConfluenceClient, ConfluenceError
     from mkdocs_to_confluence.publisher.pipeline import execute_publish, plan_publish
 
@@ -535,9 +572,6 @@ def _cmd_publish(args: argparse.Namespace) -> None:
                 nav_nodes, client, config, conf_config,
                 space_id=space_id, quiet=args.quiet, full_nav_nodes=all_nav_nodes,
             )
-            # --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,
                 space_key=conf_config.space_key,
@@ -546,6 +580,13 @@ def _cmd_publish(args: argparse.Namespace) -> None:
                 prune=getattr(args, "prune", False) and not partial,
                 quiet=args.quiet,
             )
+            # Changelog is a pinned top-level page — always publish on full runs,
+            # skip on partial runs (--page / --section) like all other publish behaviour.
+            if not partial:
+                publish_changelog(
+                    config, conf_config, client, space_id,
+                    space_key=conf_config.space_key, quiet=args.quiet,
+                )
     except ConfluenceError as exc:
         print(f"error: {exc}", file=sys.stderr)
         sys.exit(1)
@@ -599,6 +640,30 @@ def _cmd_publish(args: argparse.Namespace) -> None:
         sys.exit(1)
 
 
+def _cmd_install_skill(args: argparse.Namespace) -> None:
+    from mkdocs_to_confluence.skill_installer import install_skill
+
+    installed = install_skill(tool=getattr(args, "tool", None))
+
+    if not installed:
+        print(
+            "No AI tool directories detected and no --tool specified.\n"
+            "Run with --tool to install to a specific tool, e.g.:\n"
+            "  mk2conf install-skill --tool claude",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    for tool_name, dest in installed:
+        print(f"  installed  [{tool_name}]  {dest}")
+
+    if any(name == "fallback" for name, _ in installed):
+        print(
+            "\nNo AI tool directories were detected. Skill written to .mk2conf/changelog-skill.md.\n"
+            "Copy its contents to your AI tool's custom instructions or skill directory.",
+        )
+
+
 def _cmd_pdf(args: argparse.Namespace) -> None:
     # On macOS with uv/non-system Python, Homebrew libs are not on the dyld search
     # path.  Re-exec once with DYLD_LIBRARY_PATH set — the sentinel prevents loops.

mkdocs2confluence-0.13.0/src/mkdocs_to_confluence/compiler/__init__.py

@@ -0,0 +1,6 @@
+"""Compiler entry points for MkDocs-to-Confluence page compilation."""
+
+from mkdocs_to_confluence.compiler.models import CompileResult
+from mkdocs_to_confluence.compiler.page import compile_page
+
+__all__ = ["CompileResult", "compile_page"]

mkdocs2confluence-0.13.0/src/mkdocs_to_confluence/compiler/models.py

@@ -0,0 +1,17 @@
+"""Typed models for compiler outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CompileResult:
+    """Result of compiling a single MkDocs page to Confluence storage XHTML."""
+
+    xhtml: str
+    attachments: list[Path] = field(default_factory=list)
+    labels: tuple[str, ...] = ()
+    confluence_status: str | None = None
+    version_message: str | None = None

mkdocs2confluence-0.13.0/src/mkdocs_to_confluence/compiler/page.py

@@ -0,0 +1,110 @@
+"""Page compilation pipeline for MkDocs-to-Confluence."""
+
+from __future__ import annotations
+
+from mkdocs_to_confluence.compiler.models import CompileResult
+from mkdocs_to_confluence.emitter.xhtml import emit
+from mkdocs_to_confluence.ir.nodes import ChildrenMacro, FrontMatter, SourceFooter
+from mkdocs_to_confluence.loader.config import MkDocsConfig
+from mkdocs_to_confluence.loader.nav import NavNode
+from mkdocs_to_confluence.loader.page import load_page
+from mkdocs_to_confluence.parser.markdown import parse
+from mkdocs_to_confluence.preprocess.abbrevs import (
+    extract_abbreviations,
+    strip_abbreviation_defs,
+)
+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 (
+    preprocess_includes,
+    strip_html_comments,
+    strip_unsupported_html,
+)
+from mkdocs_to_confluence.preprocess.linkdefs import (
+    collect_link_defs,
+    expand_link_refs,
+    strip_link_defs,
+)
+from mkdocs_to_confluence.transforms.abbrevs import apply_abbreviations
+from mkdocs_to_confluence.transforms.assets import resolve_local_assets
+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
+from mkdocs_to_confluence.transforms.mermaid import DEFAULT_KROKI_URL, render_mermaid_diagrams
+
+
+def compile_page(
+    node: NavNode,
+    config: MkDocsConfig,
+    link_map: dict[str, str] | None = None,
+    *,
+    is_section_index: bool = False,
+    quiet: bool = False,
+) -> CompileResult:
+    """Run the full compile pipeline for one page and return a typed result."""
+    if node.source_path is None:
+        return CompileResult(xhtml="")
+
+    raw = load_page(node)
+
+    preprocessed = preprocess_includes(
+        raw,
+        source_path=node.source_path,
+        docs_dir=config.docs_dir,
+    )
+    preprocessed = strip_unsupported_html(preprocessed)
+    preprocessed = strip_html_comments(preprocessed)
+    preprocessed = strip_icon_shortcodes(preprocessed)
+    front_matter, preprocessed = extract_front_matter(preprocessed)
+    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)
+    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,
+        page_path=node.source_path,
+        docs_dir=config.docs_dir,
+    )
+    mermaid_render = config.confluence.mermaid_render if config.confluence else "kroki"
+    if mermaid_render != "none":
+        kroki_url = (
+            mermaid_render[len("kroki:"):] if mermaid_render.startswith("kroki:") else DEFAULT_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:
+        ir_nodes = resolve_internal_links(ir_nodes, effective_link_map, node.docs_path)
+    if front_matter is not None:
+        ir_nodes = (front_matter,) + ir_nodes
+    edit_url = config.page_edit_url(node.docs_path or "")
+    site_url = config.page_site_url(node.docs_path or "")
+    if site_url:
+        ir_nodes = attach_source_url(ir_nodes, "", site_url)
+    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,)
+
+    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
+        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}"
+
+    return CompileResult(
+        xhtml=emit(ir_nodes),
+        attachments=attachments,
+        labels=labels,
+        confluence_status=confluence_status,
+        version_message=version_message,
+    )

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.13.0}/src/mkdocs_to_confluence/loader/config.py

@@ -34,6 +34,7 @@ class ConfluenceConfig:
     github_token: str | None = None         # GitHub PAT (falls back to GITHUB_TOKEN env var)
     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
 
 
 @dataclass(frozen=True)
@@ -259,6 +260,22 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
         if not token:
             token = os.environ.get("MK2CONF_TOKEN", "")
 
+        # changelog (optional) — path relative to docs_dir
+        changelog_file: str | None = None
+        raw_changelog = raw_conf.get("changelog")
+        if raw_changelog is not None:
+            cl_str = str(raw_changelog).strip()
+            if cl_str:
+                candidate = (docs_dir / cl_str).resolve()
+                try:
+                    candidate.relative_to(docs_dir)
+                except ValueError:
+                    raise ConfigError(
+                        f"mkdocs.yml: 'confluence.changelog' path {cl_str!r} "
+                        "escapes docs_dir. The path must be relative to the docs directory."
+                    )
+                changelog_file = cl_str
+
         confluence = ConfluenceConfig(
             base_url=base_url.rstrip("/"),
             space_key=space_key,
@@ -273,6 +290,7 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
                           else os.environ.get("GITHUB_TOKEN") or None),
             github_base_branch=str(raw_conf.get("github_base_branch", "main")),
             allow_any_host=allow_any_host,
+            changelog_file=changelog_file,
         )
 
     # --- extra_css (optional) ---

mkdocs2confluence-0.13.0/src/mkdocs_to_confluence/publisher/changelog.py

@@ -0,0 +1,131 @@
+"""Compile and publish the standalone changelog page."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+from mkdocs_to_confluence.loader.nav import NavNode
+from mkdocs_to_confluence.publisher.executor import _upload_assets
+from mkdocs_to_confluence.publisher.planner import _xhtml_hash, compile_page
+
+if TYPE_CHECKING:
+    from mkdocs_to_confluence.loader.config import ConfluenceConfig, MkDocsConfig
+    from mkdocs_to_confluence.publisher.client import ConfluenceClient
+
+_FRONT_MATTER_RE = re.compile(r"\A---\s*\n(.*?\n?)---\s*\n?", re.DOTALL)
+
+
+def _extract_title(source_path: Path) -> str | None:
+    """Return the ``title`` value from YAML front matter, or ``None`` if absent."""
+    try:
+        raw = source_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    m = _FRONT_MATTER_RE.match(raw)
+    if not m:
+        return None
+    try:
+        fm: object = yaml.safe_load(m.group(1))
+    except yaml.YAMLError:
+        return None
+    if not isinstance(fm, dict):
+        return None
+    val = fm.get("title")
+    return str(val).strip() if val else None
+
+
+def publish_changelog(
+    config: MkDocsConfig,
+    conf_config: ConfluenceConfig,
+    client: ConfluenceClient,
+    space_id: str,
+    *,
+    space_key: str | None = None,
+    quiet: bool = False,
+) -> None:
+    """Compile and publish the changelog page if ``conf_config.changelog_file`` is set."""
+    if not conf_config.changelog_file:
+        return
+
+    changelog_path = config.docs_dir / conf_config.changelog_file
+    if not changelog_path.exists():
+        print(
+            f"  [warn] changelog: file not found: {changelog_path}",
+            file=sys.stderr,
+        )
+        return
+
+    title = _extract_title(changelog_path) or "What's New"
+
+    node = NavNode(
+        title=title,
+        docs_path=str(changelog_path.relative_to(config.docs_dir)),
+        source_path=changelog_path,
+        level=0,
+    )
+
+    if not quiet:
+        print(f"  compiling  '{title}'  (changelog)")
+
+    xhtml, attachments, labels, confluence_status, version_message = compile_page(
+        node, config, quiet=quiet
+    )
+
+    xhtml_hash = _xhtml_hash(xhtml)
+    existing = client.find_page(space_id, title)
+
+    if existing is not None and client.get_content_hash(str(existing["id"])) == xhtml_hash:
+        if not quiet:
+            print(f"  unchanged  '{title}'  (changelog)")
+        return
+
+    parent_id = conf_config.parent_page_id
+
+    if existing is None:
+        page = client.create_page(space_id, title, xhtml, parent_id=parent_id)
+        page_id = str(page["id"])
+        # Do NOT stamp as managed: _prune_orphans skips unmanaged pages, so
+        # this ensures --prune never deletes the changelog page.
+        if not quiet:
+            print(f"  created    '{title}'  (changelog)")
+    else:
+        page_id = str(existing["id"])
+        version: int = existing["version"]["number"]
+        client.update_page(
+            page_id, title, xhtml, version + 1,
+            parent_id=parent_id,
+            version_message=version_message,
+        )
+        if not quiet:
+            print(f"  updated    '{title}'  (changelog)")
+
+    if attachments:
+        _upload_assets(page_id, attachments, config.docs_dir, client, quiet=quiet)
+
+    try:
+        client.set_content_hash(page_id, xhtml_hash)
+    except Exception:
+        pass
+
+    if labels:
+        try:
+            client.set_page_labels(page_id, labels)
+        except Exception:
+            pass
+
+    if conf_config.full_width:
+        try:
+            client.set_page_full_width(page_id)
+        except Exception:
+            pass
+
+    if confluence_status:
+        try:
+            client.set_page_status(page_id, confluence_status, space_key=space_key)
+        except Exception:
+            pass