mkdocs2confluence 0.12.2__tar.gz → 0.13.1__tar.gz

{mkdocs2confluence-0.12.2/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.12.2
+Version: 0.13.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
@@ -153,10 +153,28 @@ 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.
+
+Run `mk2conf install-skill` once after setting `changelog:` to install the changelog AI skill into your AI tool (Claude Code, Copilot, Cursor, Hermes). The skill analyses git changes to your docs since the last `CHANGELOG.md` commit and drafts an entry when the changes qualify as significant.
+
 **Your first publish:**
 
 ```bash
@@ -172,7 +190,7 @@ mk2conf publish                                 # go live
 
 | | |
 |---|---|
-| [docs/commands.md](docs/commands.md) | Full flag reference for all four commands |
+| [docs/commands.md](docs/commands.md) | Full flag reference for all five commands |
 | [docs/features.md](docs/features.md) | Supported Markdown / Material features and known limitations |
 | [Setup.md](Setup.md) | Development environment setup |
 

{mkdocs2confluence-0.12.2 → mkdocs2confluence-0.13.1}/README.md

@@ -111,10 +111,28 @@ 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.
+
+Run `mk2conf install-skill` once after setting `changelog:` to install the changelog AI skill into your AI tool (Claude Code, Copilot, Cursor, Hermes). The skill analyses git changes to your docs since the last `CHANGELOG.md` commit and drafts an entry when the changes qualify as significant.
+
 **Your first publish:**
 
 ```bash
@@ -130,7 +148,7 @@ mk2conf publish                                 # go live
 
 | | |
 |---|---|
-| [docs/commands.md](docs/commands.md) | Full flag reference for all four commands |
+| [docs/commands.md](docs/commands.md) | Full flag reference for all five commands |
 | [docs/features.md](docs/features.md) | Supported Markdown / Material features and known limitations |
 | [Setup.md](Setup.md) | Development environment setup |
 

{mkdocs2confluence-0.12.2 → mkdocs2confluence-0.13.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.12.2"
+version = "0.13.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" }
@@ -67,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.2 → mkdocs2confluence-0.13.1/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.12.2
+Version: 0.13.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
@@ -153,10 +153,28 @@ 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.
+
+Run `mk2conf install-skill` once after setting `changelog:` to install the changelog AI skill into your AI tool (Claude Code, Copilot, Cursor, Hermes). The skill analyses git changes to your docs since the last `CHANGELOG.md` commit and drafts an entry when the changes qualify as significant.
+
 **Your first publish:**
 
 ```bash
@@ -172,7 +190,7 @@ mk2conf publish                                 # go live
 
 | | |
 |---|---|
-| [docs/commands.md](docs/commands.md) | Full flag reference for all four commands |
+| [docs/commands.md](docs/commands.md) | Full flag reference for all five commands |
 | [docs/features.md](docs/features.md) | Supported Markdown / Material features and known limitations |
 | [Setup.md](Setup.md) | Development environment setup |
 

{mkdocs2confluence-0.12.2 → mkdocs2confluence-0.13.1}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ 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
@@ -39,12 +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
@@ -61,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
@@ -84,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.2 → mkdocs2confluence-0.13.1}/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.12.2 → mkdocs2confluence-0.13.1}/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.1/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

mkdocs2confluence-0.13.1/src/mkdocs_to_confluence/skill_installer.py

@@ -0,0 +1,99 @@
+"""Install the bundled mkdocs-changelog skill into detected AI tool directories."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_FRONT_MATTER_RE = re.compile(r"\A---\s*\n.*?\n---\s*\n?", re.DOTALL)
+_SKILL_NAME = "mkdocs-changelog"
+
+
+def _read_skill() -> str:
+    from importlib.resources import files
+    return files("mkdocs_to_confluence").joinpath(f"skills/{_SKILL_NAME}/SKILL.md").read_text(encoding="utf-8")
+
+
+def _strip_front_matter(content: str) -> str:
+    return _FRONT_MATTER_RE.sub("", content).lstrip("\n")
+
+
+def install_skill(
+    project_dir: Path | None = None,
+    tool: str | None = None,
+) -> list[tuple[str, Path]]:
+    """Detect AI tools and install the changelog skill.
+
+    Args:
+        project_dir: Root of the current project (default: ``Path.cwd()``).
+        tool: If given, install only to this tool name (``hermes``, ``claude``,
+              ``copilot``, ``cursor``). Skips detection and always writes.
+
+    Returns:
+        List of ``(tool_name, install_path)`` pairs for each file written.
+    """
+    if project_dir is None:
+        project_dir = Path.cwd()
+
+    content_full = _read_skill()
+    content_body = _strip_front_matter(content_full)
+
+    installed: list[tuple[str, Path]] = []
+    explicit = tool is not None
+
+    def _want(name: str) -> bool:
+        return tool is None or tool == name
+
+    # Hermes — user-level, installed regardless of project directory
+    if _want("hermes"):
+        hermes_dir = Path.home() / ".hermes"
+        if explicit or hermes_dir.exists():
+            dest = hermes_dir / "skills" / "tooling" / _SKILL_NAME / "SKILL.md"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content_full, encoding="utf-8")
+            installed.append(("hermes", dest))
+
+    # .github/skills — project-level, skills repo format (full SKILL.md)
+    if _want("github-skills"):
+        gh_skills = project_dir / ".github" / "skills"
+        if explicit or gh_skills.exists():
+            dest = gh_skills / "tooling" / _SKILL_NAME / "SKILL.md"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content_full, encoding="utf-8")
+            installed.append(("github-skills", dest))
+
+    # Claude Code — project-level, YAML frontmatter stripped
+    if _want("claude"):
+        claude_dir = project_dir / ".claude"
+        if explicit or claude_dir.exists():
+            dest = claude_dir / "commands" / "changelog.md"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content_body, encoding="utf-8")
+            installed.append(("claude", dest))
+
+    # GitHub Copilot — project-level, body only as .instructions.md
+    if _want("copilot"):
+        copilot_marker = project_dir / ".github" / "copilot-instructions.md"
+        if explicit or copilot_marker.exists():
+            dest = project_dir / ".github" / "instructions" / "mk2conf-changelog.instructions.md"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content_body, encoding="utf-8")
+            installed.append(("copilot", dest))
+
+    # Cursor — project-level, body as .mdc
+    if _want("cursor"):
+        cursor_dir = project_dir / ".cursor"
+        if explicit or cursor_dir.exists():
+            dest = cursor_dir / "rules" / "mk2conf-changelog.mdc"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content_body, encoding="utf-8")
+            installed.append(("cursor", dest))
+
+    # Fallback — no markers detected in auto mode
+    if not installed and not explicit:
+        dest = project_dir / ".mk2conf" / "changelog-skill.md"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content_full, encoding="utf-8")
+        installed.append(("fallback", dest))
+
+    return installed

mkdocs2confluence-0.13.1/src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: mkdocs-changelog
+description: Analyse doc changes since the last CHANGELOG.md update and draft a major-change entry if the changes qualify.
+version: "1.0.0"
+tags: [documentation, git, changelog, mkdocs, confluence]
+specificity: context-specific
+tool_agnostic: true
+authors: [Anders Hybertz]
+tested_on: []
+---
+
+# MkDocs Changelog Entry
+
+Analyse git changes to the docs directory since the last `CHANGELOG.md` commit. If any changes qualify as **MAJOR**, draft a dated changelog entry and prepend it to `CHANGELOG.md`. If not, explain why and exit without modifying any file.
+
+## When to Use
+
+- After making one or more documentation changes and before running `mk2conf publish`
+- Any point in the writing flow when you want to assess whether a "What's New" entry is warranted
+
+## Steps
+
+1. **Find the baseline** — run `git log --follow -1 --format="%H" -- <docs_dir>/CHANGELOG.md` to get the last commit that touched `CHANGELOG.md`. If no commit is found, use the root commit as the baseline.
+
+2. **Collect doc changes** — run `git diff <baseline>..HEAD -- <docs_dir>/` to see everything that changed in the docs directory since that baseline.
+
+3. **Read the existing changelog** — read `<docs_dir>/CHANGELOG.md` for context on what was previously recorded.
+
+4. **Decide: is this MAJOR?**
+
+   **MAJOR criteria — any one of these qualifies:**
+   - A new top-level documentation area or section added (a new folder or nav section that didn't exist before)
+   - A significant area deleted or substantially restructured (not just moved or renamed)
+   - A fundamental definition, concept, or policy changed in a way that affects how readers understand the subject
+
+   **NOT major — do not draft an entry for:**
+   - Typo fixes, grammar corrections, spelling
+   - Formatting, diagram adjustments, image swaps
+   - Small additions (a paragraph, a note, a clarification) that do not change the substance
+   - Rewordings that preserve the original meaning
+   - Internal restructuring with no reader-facing impact
+
+5. **If NOT MAJOR** — report what was found, explain in one sentence why it did not qualify, and stop. Do not modify any file.
+
+6. **If MAJOR** — draft an entry using this format and prepend it to `CHANGELOG.md`:
+
+```markdown
+## YYYY-MM-DD — Brief title describing the major change
+
+One or two sentences summarising what fundamentally changed and why it matters to readers.
+
+### Added
+- …
+
+### Changed
+- …
+
+### Removed
+- …
+```
+
+   Rules for the entry:
+   - Date is today's date in `YYYY-MM-DD` format
+   - Sections (`Added`, `Changed`, `Removed`) are included only when non-empty
+   - No version numbers — dates only
+   - Title is a brief, reader-facing description (not a git commit message)
+
+   Prepend the entry above any existing entries in `CHANGELOG.md`. Do not commit — the user reviews, edits if needed, and commits manually.
+
+## Pitfalls
+
+- **Do not draft an entry for every change.** The changelog is for readers who want to know what fundamentally changed, not a git log. When in doubt, do not draft.
+- **Do not commit.** Always leave the file for the user to review. The user runs `git add` and `git commit` themselves before publishing.
+- **If CHANGELOG.md does not exist yet**, create it with just the new entry (no header needed).
+
+## Verification
+
+After drafting, show the user the proposed entry in the terminal and remind them to review `CHANGELOG.md` before committing and running `mk2conf publish`.