mkdocs2confluence 0.13.7__tar.gz → 0.13.8__tar.gz

{mkdocs2confluence-0.13.7/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.13.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.7
+Version: 0.13.8
 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

{mkdocs2confluence-0.13.7 → mkdocs2confluence-0.13.8}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.7
+Version: 0.13.8
 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

{mkdocs2confluence-0.13.7 → mkdocs2confluence-0.13.8}/src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.3.0"
+version: "1.4.0"
 tags: [documentation, git, changelog, mkdocs, confluence]
 specificity: context-specific
 tool_agnostic: true
@@ -64,6 +64,30 @@ Analyse git changes to the docs directory since the last `CHANGELOG.md` commit.
    `CHANGELOG.md`. The previous latest entry (if any) must be converted from `???+` to `???`
    so only the new entry is expanded by default.
 
+## Linking to changed pages
+
+The `changes` object in the script JSON now includes `{"path": "...", "title": "..."}` for
+each file. Use this to link readers directly to the most relevant pages — but only where
+it adds value and reads naturally.
+
+Rules:
+
+- **Select, don't list.** Pick at most two or three files per entry — the ones a reader
+  would actually want to visit. Omit files that are supporting material (images, assets,
+  index stubs, nav-only pages).
+- **Weave into prose**, not as a separate list. Example:
+
+  Good: `Updated the [Configuration reference](configuration/index.md) to cover the new auth options.`
+  Bad: `Updated configuration/index.md. See also: getting-started.md, reference.md.`
+
+- **Use `title` as link text** when it reads naturally. Fall back to a short descriptive
+  phrase if the title is too long or too generic (e.g. "Overview", "Index").
+- **Paths are relative to `docs_dir`**, and `CHANGELOG.md` lives at the root of `docs_dir`.
+  A file at `docs/configuration/index.md` links as `configuration/index.md`.
+- **Deleted pages** — do not link to them. Name them in prose without a link.
+- **Skip linking entirely** if the change is a typo fix, formatting pass, or other
+  non-substantive update — linking draws attention and signals importance.
+
 ## Entry format
 
 The latest entry uses `???+` (expanded by default on Material, always visible on Confluence).

{mkdocs2confluence-0.13.7 → mkdocs2confluence-0.13.8}/src/mkdocs_to_confluence/skills/mkdocs-changelog/scripts/changelog_data.py

@@ -12,9 +12,11 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import subprocess
 import sys
 from datetime import date
+from pathlib import Path
 
 
 def _run(args: list[str]) -> str:
@@ -69,8 +71,30 @@ def _commits_since(baseline: str) -> list[dict[str, str]]:
     return commits
 
 
-def _changed_files(baseline: str, docs_dir: str) -> dict[str, list[str]]:
-    """Return files changed in docs_dir since baseline, grouped by status."""
+def _extract_title(file_path: str) -> str | None:
+    """Return the first H1 heading from a markdown file, or None if unreadable."""
+    try:
+        text = Path(file_path).read_text(encoding="utf-8", errors="replace")
+        for line in text.splitlines():
+            m = re.match(r"^#\s+(.+)", line)
+            if m:
+                return m.group(1).strip()
+    except OSError:
+        pass
+    return None
+
+
+def _enrich(paths: list[str]) -> list[dict[str, str | None]]:
+    """Attach page titles to file paths. Non-.md files get title=None."""
+    result = []
+    for p in paths:
+        title = _extract_title(p) if p.endswith(".md") else None
+        result.append({"path": p, "title": title})
+    return result
+
+
+def _changed_files(baseline: str, docs_dir: str) -> dict[str, list[dict[str, str | None]]]:
+    """Return files changed in docs_dir since baseline, grouped by status, with titles."""
     raw = _run([
         "git", "diff", "--name-status", f"{baseline}..HEAD", "--", docs_dir,
     ])
@@ -78,7 +102,7 @@ def _changed_files(baseline: str, docs_dir: str) -> dict[str, list[str]]:
     modified: list[str] = []
     deleted: list[str] = []
     if not raw:
-        return {"added": added, "modified": modified, "deleted": deleted}
+        return {"added": _enrich(added), "modified": _enrich(modified), "deleted": _enrich(deleted)}
     for line in raw.splitlines():
         parts = line.split("\t", maxsplit=1)
         if len(parts) != 2:  # noqa: PLR2004
@@ -90,7 +114,7 @@ def _changed_files(baseline: str, docs_dir: str) -> dict[str, list[str]]:
             deleted.append(path)
         elif status.startswith("M") or status.startswith("R") or status.startswith("C"):
             modified.append(path)
-    return {"added": added, "modified": modified, "deleted": deleted}
+    return {"added": _enrich(added), "modified": _enrich(modified), "deleted": _enrich(deleted)}
 
 
 def _contributors(commits: list[dict[str, str]]) -> list[str]: