mkdocs2confluence 0.9.0__tar.gz → 0.9.1__tar.gz

{mkdocs2confluence-0.9.0 → mkdocs2confluence-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.0
+Version: 0.9.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

{mkdocs2confluence-0.9.0 → mkdocs2confluence-0.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.9.0"
+version = "0.9.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" }

{mkdocs2confluence-0.9.0 → mkdocs2confluence-0.9.1}/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.0
+Version: 0.9.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

{mkdocs2confluence-0.9.0 → mkdocs2confluence-0.9.1}/src/mkdocs_to_confluence/emitter/xhtml.py

@@ -251,19 +251,38 @@ def _emit_front_matter(node: FrontMatter) -> str:
     return "".join(parts)
 
 
+def _xml_safe(text: str) -> str:
+    """HTML-escape *text* and encode non-ASCII as XML numeric character references.
+
+    Confluence storage format is XML; raw non-ASCII bytes (e.g. UTF-8 encoded ·)
+    can be misinterpreted as Latin-1 by some Confluence versions, producing artefacts
+    like ``·``.  Encoding everything outside ASCII as ``&#NNN;`` entities is safe
+    for all Confluence deployments.
+    """
+    return html.escape(text).encode("ascii", "xmlcharrefreplace").decode()
+
+
 def _emit_source_footer(node: SourceFooter) -> str:
-    """Emit a 'Page source' panel macro with edit/history links and last-commit info."""
+    """Emit a borderless panel macro with edit/history links and last-commit info."""
     edit_href = html.escape(node.edit_url)
     links = f'<a href="{edit_href}">Edit this page</a>'
     if node.history_url:
         hist_href = html.escape(node.history_url)
-        links += f' \u00b7 <a href="{hist_href}">View history</a>'
+        links += f' &#xB7; <a href="{hist_href}">View history</a>'
     body = f"<p>{links}</p>\n"
-    if node.last_commit:
-        body += f"<p><em>Last commit: {html.escape(node.last_commit)}</em></p>\n"
+    if node.commit_sha or node.commit_summary:
+        if node.commit_sha and node.commit_url:
+            sha_href = html.escape(node.commit_url)
+            sha_part = f'<a href="{sha_href}">{html.escape(node.commit_sha)}</a>'
+        elif node.commit_sha:
+            sha_part = html.escape(node.commit_sha)
+        else:
+            sha_part = ""
+        summary_part = _xml_safe(node.commit_summary) if node.commit_summary else ""
+        detail = " &#xB7; ".join(p for p in [sha_part, summary_part] if p)
+        body += f"<p><strong>Last commit:</strong> {detail}</p>\n"
     return (
         '<ac:structured-macro ac:name="panel">\n'
-        '  <ac:parameter ac:name="title">Page source</ac:parameter>\n'
         '  <ac:parameter ac:name="borderStyle">solid</ac:parameter>\n'
         "  <ac:rich-text-body>\n"
         f"    {body}"

{mkdocs2confluence-0.9.0 → mkdocs2confluence-0.9.1}/src/mkdocs_to_confluence/ir/nodes.py

@@ -435,17 +435,23 @@ class SourceFooter(IRNode):
     Emitted as a Confluence ``panel`` macro at the bottom of the page.
 
     Attributes:
-        edit_url:     URL to edit the source file (e.g. GitHub edit link).
-        history_url:  URL to the file's commit history.  ``None`` when it
-                      cannot be derived from ``edit_url``.
-        last_commit:  Human-readable last-commit summary from ``git log``,
-                      e.g. ``"abc1234 · Fix typo · Jane · 2 days ago"``.
-                      ``None`` when git is unavailable or the file is untracked.
+        edit_url:        URL to edit the source file (e.g. GitHub edit link).
+        history_url:     URL to the file's commit history.  ``None`` when it
+                         cannot be derived from ``edit_url``.
+        commit_sha:      Short commit hash (e.g. ``"abc1234"``).  ``None`` when
+                         git is unavailable or the file is untracked.
+        commit_url:      URL to the specific commit on the VCS host.  ``None``
+                         when the URL cannot be derived.
+        commit_summary:  Commit message, author, and relative date, e.g.
+                         ``"Fix typo · Jane · 2 days ago"``.  ``None`` when git
+                         is unavailable or the file is untracked.
     """
 
     edit_url: str
     history_url: str | None = None
-    last_commit: str | None = None
+    commit_sha: str | None = None
+    commit_url: str | None = None
+    commit_summary: str | None = None
 
 
 @dataclass(frozen=True)

{mkdocs2confluence-0.9.0 → mkdocs2confluence-0.9.1}/src/mkdocs_to_confluence/transforms/footer.py

@@ -11,6 +11,9 @@ import subprocess
 
 from mkdocs_to_confluence.ir.nodes import SourceFooter
 
+# separator used in git --format to allow reliable splitting
+_GIT_SEP = "\x1f"  # ASCII unit separator — never appears in commit messages
+
 
 def _derive_history_url(edit_url: str) -> str | None:
     """Derive a commit-history URL from a VCS edit URL.
@@ -25,18 +28,34 @@ def _derive_history_url(edit_url: str) -> str | None:
     return None
 
 
-def _last_commit(abs_path: str) -> str | None:
-    """Return a human-readable last-commit summary for *abs_path*.
+def _derive_commit_url(edit_url: str, sha: str) -> str | None:
+    """Derive a direct commit URL from a VCS edit URL and a commit SHA.
 
-    Runs ``git log -1 --format=... --date=relative`` on the file.
+    Supports GitHub (``/edit/``) and GitLab (``/-/edit/``).
+    Returns ``None`` for any other URL shape.
+    """
+    if "/-/edit/" in edit_url:
+        base = edit_url.split("/-/edit/")[0]
+        return f"{base}/-/commit/{sha}"
+    if "/edit/" in edit_url:
+        base = edit_url.split("/edit/")[0]
+        return f"{base}/commit/{sha}"
+    return None
+
+
+def _last_commit_info(abs_path: str) -> tuple[str, str] | None:
+    """Return ``(short_sha, summary)`` for the last commit touching *abs_path*.
+
+    *summary* is ``"message · author · relative_date"``.
     Returns ``None`` when git is unavailable, the path is untracked, or the
     command fails for any reason.
     """
+    sep = _GIT_SEP
     try:
         result = subprocess.run(
             [
                 "git", "log", "-1",
-                "--format=%h \u00b7 %s \u00b7 %an \u00b7 %ad",
+                f"--format=%h{sep}%s{sep}%an{sep}%ad",
                 "--date=relative",
                 "--",
                 abs_path,
@@ -46,7 +65,13 @@ def _last_commit(abs_path: str) -> str | None:
             timeout=5,
         )
         output = result.stdout.strip()
-        return output if output else None
+        if not output:
+            return None
+        parts = output.split(sep, 3)
+        if len(parts) < 4:
+            return None
+        sha, message, author, date = parts
+        return sha, f"{message} \u00b7 {author} \u00b7 {date}"
     except Exception:  # noqa: BLE001
         return None
 
@@ -62,8 +87,19 @@ def build_source_footer(edit_url: str, abs_path: str) -> SourceFooter:
         Absolute filesystem path to the source Markdown file.  Used to
         query ``git log`` for the last-commit summary.
     """
+    commit_info = _last_commit_info(abs_path)
+    if commit_info is not None:
+        sha, summary = commit_info
+        commit_url = _derive_commit_url(edit_url, sha)
+    else:
+        sha = None
+        summary = None
+        commit_url = None
+
     return SourceFooter(
         edit_url=edit_url,
         history_url=_derive_history_url(edit_url),
-        last_commit=_last_commit(abs_path),
+        commit_sha=sha,
+        commit_url=commit_url,
+        commit_summary=summary,
     )

mkdocs2confluence-0.9.1/tests/test_footer.py

@@ -0,0 +1,217 @@
+"""Tests for transforms/footer.py and the SourceFooter emitter."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from mkdocs_to_confluence.emitter.xhtml import emit
+from mkdocs_to_confluence.ir.nodes import SourceFooter
+from mkdocs_to_confluence.transforms.footer import (
+    _derive_commit_url,
+    _derive_history_url,
+    _last_commit_info,
+    build_source_footer,
+)
+
+# ── _derive_history_url ───────────────────────────────────────────────────────
+
+
+def test_derive_history_url_github():
+    url = "https://github.com/org/repo/edit/main/docs/guide/setup.md"
+    assert _derive_history_url(url) == "https://github.com/org/repo/commits/main/docs/guide/setup.md"
+
+
+def test_derive_history_url_gitlab():
+    url = "https://gitlab.com/org/repo/-/edit/main/docs/guide/setup.md"
+    assert _derive_history_url(url) == "https://gitlab.com/org/repo/-/commits/main/docs/guide/setup.md"
+
+
+def test_derive_history_url_unknown_returns_none():
+    url = "https://bitbucket.org/org/repo/src/main/docs/guide/setup.md"
+    assert _derive_history_url(url) is None
+
+
+def test_derive_history_url_empty_string():
+    assert _derive_history_url("") is None
+
+
+# ── _derive_commit_url ────────────────────────────────────────────────────────
+
+
+def test_derive_commit_url_github():
+    url = "https://github.com/org/repo/edit/main/docs/page.md"
+    assert _derive_commit_url(url, "abc1234") == "https://github.com/org/repo/commit/abc1234"
+
+
+def test_derive_commit_url_gitlab():
+    url = "https://gitlab.com/org/repo/-/edit/main/docs/page.md"
+    assert _derive_commit_url(url, "abc1234") == "https://gitlab.com/org/repo/-/commit/abc1234"
+
+
+def test_derive_commit_url_unknown_returns_none():
+    url = "https://bitbucket.org/org/repo/src/main/docs/page.md"
+    assert _derive_commit_url(url, "abc1234") is None
+
+
+# ── _last_commit_info ─────────────────────────────────────────────────────────
+
+
+def test_last_commit_info_returns_sha_and_summary(tmp_path):
+    fake_file = str(tmp_path / "docs" / "page.md")
+    sep = "\x1f"
+    with patch("mkdocs_to_confluence.transforms.footer.subprocess.run") as mock_run:
+        mock_run.return_value.stdout = f"abc1234{sep}Fix typo{sep}Jane{sep}2 days ago\n"
+        result = _last_commit_info(fake_file)
+    assert result is not None
+    sha, summary = result
+    assert sha == "abc1234"
+    assert "Fix typo" in summary
+    assert "Jane" in summary
+    assert "2 days ago" in summary
+
+
+def test_last_commit_info_returns_none_when_empty(tmp_path):
+    fake_file = str(tmp_path / "docs" / "untracked.md")
+    with patch("mkdocs_to_confluence.transforms.footer.subprocess.run") as mock_run:
+        mock_run.return_value.stdout = ""
+        result = _last_commit_info(fake_file)
+    assert result is None
+
+
+def test_last_commit_info_returns_none_on_exception(tmp_path):
+    fake_file = str(tmp_path / "docs" / "page.md")
+    with patch("mkdocs_to_confluence.transforms.footer.subprocess.run", side_effect=FileNotFoundError):
+        result = _last_commit_info(fake_file)
+    assert result is None
+
+
+# ── build_source_footer ───────────────────────────────────────────────────────
+
+
+def test_build_source_footer_full(tmp_path):
+    edit_url = "https://github.com/org/repo/edit/main/docs/guide.md"
+    abs_path = str(tmp_path / "docs" / "guide.md")
+    with patch("mkdocs_to_confluence.transforms.footer._last_commit_info",
+               return_value=("abc1234", "Fix typo · Jane · 1 day ago")):
+        footer = build_source_footer(edit_url, abs_path)
+    assert footer.edit_url == edit_url
+    assert footer.history_url == "https://github.com/org/repo/commits/main/docs/guide.md"
+    assert footer.commit_sha == "abc1234"
+    assert footer.commit_url == "https://github.com/org/repo/commit/abc1234"
+    assert footer.commit_summary == "Fix typo · Jane · 1 day ago"
+
+
+def test_build_source_footer_no_commit(tmp_path):
+    edit_url = "https://github.com/org/repo/edit/main/docs/guide.md"
+    abs_path = str(tmp_path / "docs" / "guide.md")
+    with patch("mkdocs_to_confluence.transforms.footer._last_commit_info", return_value=None):
+        footer = build_source_footer(edit_url, abs_path)
+    assert footer.commit_sha is None
+    assert footer.commit_url is None
+    assert footer.commit_summary is None
+    assert footer.history_url is not None
+
+
+# ── _emit_source_footer ───────────────────────────────────────────────────────
+
+
+def test_emit_footer_contains_edit_link():
+    footer = SourceFooter(
+        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
+        history_url="https://github.com/org/repo/commits/main/docs/page.md",
+        commit_sha="abc1234",
+        commit_url="https://github.com/org/repo/commit/abc1234",
+        commit_summary="Fix typo · Jane · 2 days ago",
+    )
+    out = emit((footer,))
+    assert "Edit this page" in out
+    assert "View history" in out
+    assert "abc1234" in out
+    assert "Fix typo" in out
+    assert 'ac:name="panel"' in out
+
+
+def test_emit_footer_sha_is_hyperlink():
+    footer = SourceFooter(
+        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
+        history_url=None,
+        commit_sha="abc1234",
+        commit_url="https://github.com/org/repo/commit/abc1234",
+        commit_summary="Fix typo · Jane · today",
+    )
+    out = emit((footer,))
+    assert 'href="https://github.com/org/repo/commit/abc1234"' in out
+    assert ">abc1234<" in out
+
+
+def test_emit_footer_last_commit_bold():
+    footer = SourceFooter(
+        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
+        history_url=None,
+        commit_sha="abc1234",
+        commit_url="https://github.com/org/repo/commit/abc1234",
+        commit_summary="Fix typo · Jane · today",
+    )
+    out = emit((footer,))
+    assert "<strong>Last commit:</strong>" in out
+
+
+def test_emit_footer_no_panel_title():
+    footer = SourceFooter(
+        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
+    )
+    out = emit((footer,))
+    assert 'ac:name="title"' not in out
+
+
+def test_emit_footer_no_history_url():
+    footer = SourceFooter(
+        edit_url="https://example.com/edit/docs/page.md",
+        history_url=None,
+        commit_sha=None,
+        commit_url=None,
+        commit_summary=None,
+    )
+    out = emit((footer,))
+    assert "Edit this page" in out
+    assert "View history" not in out
+    assert "Last commit" not in out
+
+
+def test_emit_footer_escapes_html():
+    footer = SourceFooter(
+        edit_url='https://example.com/edit/path?a=1&b=2',
+        history_url=None,
+        commit_sha=None,
+        commit_url=None,
+        commit_summary='<script>alert(1)</script> · Jane · today',
+    )
+    out = emit((footer,))
+    assert "<script>" not in out
+    assert "&lt;script&gt;" in out
+    assert "a=1&amp;b=2" in out
+
+
+def test_emit_footer_non_ascii_encoded_as_entity():
+    """Non-ASCII characters in commit_summary are encoded as XML numeric entities."""
+    footer = SourceFooter(
+        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
+        history_url=None,
+        commit_sha=None,
+        commit_url=None,
+        commit_summary="Fix caf\u00e9 · \u00c5ngstr\u00f6m · 2 days ago",
+    )
+    out = emit((footer,))
+    assert "caf\u00e9" not in out
+    assert "&#233;" in out or "&#xe9;" in out.lower()
+
+
+def test_emit_footer_separator_is_entity():
+    """The · separator between Edit/View history links is an XML entity, not raw UTF-8."""
+    footer = SourceFooter(
+        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
+        history_url="https://github.com/org/repo/commits/main/docs/page.md",
+    )
+    out = emit((footer,))
+    assert "&#xB7;" in out
+    assert "\u00b7" not in out

mkdocs2confluence-0.9.0/tests/test_footer.py

@@ -1,119 +0,0 @@
-"""Tests for transforms/footer.py and the SourceFooter emitter."""
-
-from __future__ import annotations
-
-from unittest.mock import patch
-
-from mkdocs_to_confluence.emitter.xhtml import emit
-from mkdocs_to_confluence.ir.nodes import SourceFooter
-from mkdocs_to_confluence.transforms.footer import _derive_history_url, _last_commit, build_source_footer
-
-# ── _derive_history_url ───────────────────────────────────────────────────────
-
-
-def test_derive_history_url_github():
-    url = "https://github.com/org/repo/edit/main/docs/guide/setup.md"
-    assert _derive_history_url(url) == "https://github.com/org/repo/commits/main/docs/guide/setup.md"
-
-
-def test_derive_history_url_gitlab():
-    url = "https://gitlab.com/org/repo/-/edit/main/docs/guide/setup.md"
-    assert _derive_history_url(url) == "https://gitlab.com/org/repo/-/commits/main/docs/guide/setup.md"
-
-
-def test_derive_history_url_unknown_returns_none():
-    url = "https://bitbucket.org/org/repo/src/main/docs/guide/setup.md"
-    assert _derive_history_url(url) is None
-
-
-def test_derive_history_url_empty_string():
-    assert _derive_history_url("") is None
-
-
-# ── _last_commit ──────────────────────────────────────────────────────────────
-
-
-def test_last_commit_returns_output(tmp_path):
-    fake_file = str(tmp_path / "docs" / "page.md")
-    with patch("mkdocs_to_confluence.transforms.footer.subprocess.run") as mock_run:
-        mock_run.return_value.stdout = "abc1234 · Fix typo · Jane · 2 days ago\n"
-        result = _last_commit(fake_file)
-    assert result == "abc1234 · Fix typo · Jane · 2 days ago"
-
-
-def test_last_commit_returns_none_when_empty(tmp_path):
-    fake_file = str(tmp_path / "docs" / "untracked.md")
-    with patch("mkdocs_to_confluence.transforms.footer.subprocess.run") as mock_run:
-        mock_run.return_value.stdout = ""
-        result = _last_commit(fake_file)
-    assert result is None
-
-
-def test_last_commit_returns_none_on_exception(tmp_path):
-    fake_file = str(tmp_path / "docs" / "page.md")
-    with patch("mkdocs_to_confluence.transforms.footer.subprocess.run", side_effect=FileNotFoundError):
-        result = _last_commit(fake_file)
-    assert result is None
-
-
-# ── build_source_footer ───────────────────────────────────────────────────────
-
-
-def test_build_source_footer_full(tmp_path):
-    edit_url = "https://github.com/org/repo/edit/main/docs/guide.md"
-    abs_path = str(tmp_path / "docs" / "guide.md")
-    with patch("mkdocs_to_confluence.transforms.footer._last_commit", return_value="abc · msg · Jane · 1 day ago"):
-        footer = build_source_footer(edit_url, abs_path)
-    assert footer.edit_url == edit_url
-    assert footer.history_url == "https://github.com/org/repo/commits/main/docs/guide.md"
-    assert footer.last_commit == "abc · msg · Jane · 1 day ago"
-
-
-def test_build_source_footer_no_commit(tmp_path):
-    edit_url = "https://github.com/org/repo/edit/main/docs/guide.md"
-    abs_path = str(tmp_path / "docs" / "guide.md")
-    with patch("mkdocs_to_confluence.transforms.footer._last_commit", return_value=None):
-        footer = build_source_footer(edit_url, abs_path)
-    assert footer.last_commit is None
-    assert footer.history_url is not None
-
-
-# ── _emit_source_footer ───────────────────────────────────────────────────────
-
-
-def test_emit_footer_contains_edit_link():
-    footer = SourceFooter(
-        edit_url="https://github.com/org/repo/edit/main/docs/page.md",
-        history_url="https://github.com/org/repo/commits/main/docs/page.md",
-        last_commit="abc1234 · Fix typo · Jane · 2 days ago",
-    )
-    out = emit((footer,))
-    assert "Edit this page" in out
-    assert "View history" in out
-    assert "abc1234" in out
-    assert "Fix typo" in out
-    assert 'ac:name="panel"' in out
-
-
-def test_emit_footer_no_history_url():
-    footer = SourceFooter(
-        edit_url="https://example.com/edit/docs/page.md",
-        history_url=None,
-        last_commit=None,
-    )
-    out = emit((footer,))
-    assert "Edit this page" in out
-    assert "View history" not in out
-    assert "Last commit" not in out
-
-
-def test_emit_footer_escapes_html():
-    footer = SourceFooter(
-        edit_url='https://example.com/edit/path?a=1&b=2',
-        history_url=None,
-        last_commit='abc · <script>alert(1)</script> · Jane · today',
-    )
-    out = emit((footer,))
-    assert "<script>" not in out
-    assert "&lt;script&gt;" in out
-    assert "a=1&amp;b=2" in out