mkdocs2confluence 0.13.6__tar.gz → 0.13.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.6
+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.6 → mkdocs2confluence-0.13.8}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.6
+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.6 → 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.2.0"
+version: "1.4.0"
 tags: [documentation, git, changelog, mkdocs, confluence]
 specificity: context-specific
 tool_agnostic: true
@@ -22,15 +22,24 @@ Analyse git changes to the docs directory since the last `CHANGELOG.md` commit.
 
 1. **Extract git data** — run the bundled data script to get structured, deterministic input:
 
+   Normal update (since last CHANGELOG.md commit):
    ```
    python .mk2conf/scripts/changelog_data.py --docs-dir <docs_dir>
    ```
 
+   Initial changelog (from a specific date):
+   ```
+   python .mk2conf/scripts/changelog_data.py --docs-dir <docs_dir> --since YYYY-MM-DD
+   ```
+
    The script prints a JSON object to stdout. Use this as your sole source of truth for
    commits, changed files, and contributors. Do not run git commands yourself.
 
    If the script is missing, tell the user to run `mk2conf install-skill` first.
 
+   When `--since` is used, the JSON will contain `"mode": "since_date"`. Use this to
+   trigger the initial changelog flow described below.
+
 2. **Read the existing changelog** — read `<docs_dir>/CHANGELOG.md` for context on what
    was previously recorded.
 
@@ -55,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).
@@ -109,6 +142,26 @@ All notable changes to this documentation are recorded here.
 The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ```
 
+## Initial changelog (--since DATE)
+
+When the script is run with `--since` and the JSON contains `"mode": "since_date"`,
+the user wants to bootstrap a CHANGELOG.md from scratch for a given time window.
+
+Different rules apply:
+
+- **Always draft** — the MAJOR threshold does not apply. This is a retrospective
+  summary, not an incremental gate.
+- **Group by theme**, not by individual commit. Synthesise the changed files and
+  commit subjects into meaningful categories.
+- **Date range in the title** — use the `since` value from the JSON as the start
+  and `date` as the end, e.g. `2026-05-01 → 2026-05-27`.
+- **If CHANGELOG.md already exists**, stop and ask the user whether they want to
+  prepend, append, or replace. Do not overwrite silently.
+- **If CHANGELOG.md does not exist**, create it with the standard header and the
+  entry as `???+`.
+
+Example title: `2026-05-01 → 2026-05-27 — Initial documentation release`
+
 ## Pitfalls
 
 - **Do not draft an entry for every change.** The changelog is for readers who want to know

{mkdocs2confluence-0.13.6 → 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:
@@ -37,6 +39,16 @@ def _baseline_commit(changelog_path: str) -> str | None:
     return sha or None
 
 
+def _commit_before_date(since_date: str) -> str | None:
+    """Return the SHA of the last commit strictly before since_date (YYYY-MM-DD), or None."""
+    sha = _run([
+        "git", "log", "--format=%H",
+        f"--before={since_date}",
+        "-1",
+    ])
+    return sha or None
+
+
 def _root_commit() -> str:
     """Return the SHA of the very first commit in the repo."""
     return _run(["git", "rev-list", "--max-parents=0", "HEAD"])
@@ -59,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,
     ])
@@ -68,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
@@ -80,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]:
@@ -102,19 +136,39 @@ def main() -> None:
         default="docs",
         help="Path to the MkDocs docs directory, relative to project root (default: docs)",
     )
+    parser.add_argument(
+        "--since",
+        metavar="DATE",
+        default=None,
+        help=(
+            "Use the last commit before DATE (YYYY-MM-DD) as the baseline instead of the "
+            "last commit that touched CHANGELOG.md. Useful for creating an initial changelog."
+        ),
+    )
     args = parser.parse_args()
 
     docs_dir: str = args.docs_dir
     changelog_rel = f"{docs_dir}/CHANGELOG.md"
 
-    # Baseline: last commit touching CHANGELOG.md, or root commit if none
-    baseline = _baseline_commit(changelog_rel) or _root_commit()
-    if not baseline:
-        print(
-            "error: could not determine a baseline commit — is this a git repository?",
-            file=sys.stderr,
-        )
-        sys.exit(1)
+    # Baseline resolution — --since takes priority
+    if args.since:
+        baseline = _commit_before_date(args.since)
+        if not baseline:
+            print(
+                f"error: no commit found before {args.since}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        mode = "since_date"
+    else:
+        baseline = _baseline_commit(changelog_rel) or _root_commit()
+        if not baseline:
+            print(
+                "error: could not determine a baseline commit — is this a git repository?",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        mode = "changelog_commit"
 
     commits = _commits_since(baseline)
     changes = _changed_files(baseline, docs_dir)
@@ -122,6 +176,8 @@ def main() -> None:
 
     output = {
         "date": date.today().isoformat(),
+        "mode": mode,
+        "since": args.since,
         "baseline_commit": baseline,
         "commits": commits,
         "contributors": contributors,