mkdocs2confluence 0.9.4__tar.gz → 0.9.6__tar.gz

{mkdocs2confluence-0.9.4 → mkdocs2confluence-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.4
+Version: 0.9.6
 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
@@ -245,6 +245,8 @@ mk2conf publish [--config PATH] [--page PATH] [--section SECTION] [--dry-run] [-
 
 If Kroki is unreachable the run continues, falling back to the `code` macro for affected diagrams.
 
+**Automatic mermaid.ink fallback:** when using the public `kroki.io` service and a Mermaid diagram receives a 504 (gateway timeout), mk2conf automatically retries that diagram via [mermaid.ink](https://mermaid.ink) before giving up. No configuration needed — the fallback is transparent and only applies to Mermaid diagrams on the public service. Self-hosted Kroki instances never contact mermaid.ink, preserving network isolation.
+
 #### Styling from extra.css
 
 If `mkdocs.yml` lists `extra_css:` files, mk2conf reads them and applies a whitelisted set of CSS properties as inline `style="..."` attributes on Confluence output.
@@ -368,6 +370,7 @@ confluence:
 | `^^inserted^^` | `<u>` (pymdownx.caret insert) |
 | `` `inline code` `` | `<code>` |
 | `[text](url)` | `<a href="...">` |
+| `[text][label]` / `[text][]` with `[label]: url` | Resolved to inline link before parsing |
 | `https://bare-url` | `<a href="...">` (autolink) |
 | `[text](file.pdf)` | `<ac:link><ri:attachment .../>` (uploaded as attachment) |
 | `![alt](src)` | `<ac:image>` with `<ri:attachment>` (local) or `<ri:url>` (remote) |
@@ -433,6 +436,8 @@ When `repo_url` + `edit_uri` are set in `mkdocs.yml`, a **Page source** footer p
 - **View history** — links to the file's commit history (derived automatically for GitHub and GitLab URLs)
 - **Last commit** — short commit SHA (linked to that commit), message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
 
+The commit SHA and message are also written to the **Confluence version history** on every publish (`sha: message`), so the page history in Confluence stays in sync with your git log.
+
 ### Section index child pages
 
 When a MkDocs navigation section has an `index.md`, the published Confluence page automatically includes the native **Children Display macro** below the page content. This renders a live, auto-maintained list of all direct child pages — no manual curation needed. The macro is injected by default on every section index page.

{mkdocs2confluence-0.9.4 → mkdocs2confluence-0.9.6}/README.md

@@ -205,6 +205,8 @@ mk2conf publish [--config PATH] [--page PATH] [--section SECTION] [--dry-run] [-
 
 If Kroki is unreachable the run continues, falling back to the `code` macro for affected diagrams.
 
+**Automatic mermaid.ink fallback:** when using the public `kroki.io` service and a Mermaid diagram receives a 504 (gateway timeout), mk2conf automatically retries that diagram via [mermaid.ink](https://mermaid.ink) before giving up. No configuration needed — the fallback is transparent and only applies to Mermaid diagrams on the public service. Self-hosted Kroki instances never contact mermaid.ink, preserving network isolation.
+
 #### Styling from extra.css
 
 If `mkdocs.yml` lists `extra_css:` files, mk2conf reads them and applies a whitelisted set of CSS properties as inline `style="..."` attributes on Confluence output.
@@ -328,6 +330,7 @@ confluence:
 | `^^inserted^^` | `<u>` (pymdownx.caret insert) |
 | `` `inline code` `` | `<code>` |
 | `[text](url)` | `<a href="...">` |
+| `[text][label]` / `[text][]` with `[label]: url` | Resolved to inline link before parsing |
 | `https://bare-url` | `<a href="...">` (autolink) |
 | `[text](file.pdf)` | `<ac:link><ri:attachment .../>` (uploaded as attachment) |
 | `![alt](src)` | `<ac:image>` with `<ri:attachment>` (local) or `<ri:url>` (remote) |
@@ -393,6 +396,8 @@ When `repo_url` + `edit_uri` are set in `mkdocs.yml`, a **Page source** footer p
 - **View history** — links to the file's commit history (derived automatically for GitHub and GitLab URLs)
 - **Last commit** — short commit SHA (linked to that commit), message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
 
+The commit SHA and message are also written to the **Confluence version history** on every publish (`sha: message`), so the page history in Confluence stays in sync with your git log.
+
 ### Section index child pages
 
 When a MkDocs navigation section has an `index.md`, the published Confluence page automatically includes the native **Children Display macro** below the page content. This renders a live, auto-maintained list of all direct child pages — no manual curation needed. The macro is injected by default on every section index page.

{mkdocs2confluence-0.9.4 → mkdocs2confluence-0.9.6}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.9.4
+Version: 0.9.6
 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
@@ -245,6 +245,8 @@ mk2conf publish [--config PATH] [--page PATH] [--section SECTION] [--dry-run] [-
 
 If Kroki is unreachable the run continues, falling back to the `code` macro for affected diagrams.
 
+**Automatic mermaid.ink fallback:** when using the public `kroki.io` service and a Mermaid diagram receives a 504 (gateway timeout), mk2conf automatically retries that diagram via [mermaid.ink](https://mermaid.ink) before giving up. No configuration needed — the fallback is transparent and only applies to Mermaid diagrams on the public service. Self-hosted Kroki instances never contact mermaid.ink, preserving network isolation.
+
 #### Styling from extra.css
 
 If `mkdocs.yml` lists `extra_css:` files, mk2conf reads them and applies a whitelisted set of CSS properties as inline `style="..."` attributes on Confluence output.
@@ -368,6 +370,7 @@ confluence:
 | `^^inserted^^` | `<u>` (pymdownx.caret insert) |
 | `` `inline code` `` | `<code>` |
 | `[text](url)` | `<a href="...">` |
+| `[text][label]` / `[text][]` with `[label]: url` | Resolved to inline link before parsing |
 | `https://bare-url` | `<a href="...">` (autolink) |
 | `[text](file.pdf)` | `<ac:link><ri:attachment .../>` (uploaded as attachment) |
 | `![alt](src)` | `<ac:image>` with `<ri:attachment>` (local) or `<ri:url>` (remote) |
@@ -433,6 +436,8 @@ When `repo_url` + `edit_uri` are set in `mkdocs.yml`, a **Page source** footer p
 - **View history** — links to the file's commit history (derived automatically for GitHub and GitLab URLs)
 - **Last commit** — short commit SHA (linked to that commit), message, author, and relative date from `git log` at publish time (omitted if git is unavailable or the file is untracked)
 
+The commit SHA and message are also written to the **Confluence version history** on every publish (`sha: message`), so the page history in Confluence stays in sync with your git log.
+
 ### Section index child pages
 
 When a MkDocs navigation section has an `index.md`, the published Confluence page automatically includes the native **Children Display macro** below the page content. This renders a live, auto-maintained list of all direct child pages — no manual curation needed. The macro is injected by default on every section index page.

{mkdocs2confluence-0.9.4 → mkdocs2confluence-0.9.6}/src/mkdocs_to_confluence/transforms/mermaid.py

@@ -10,17 +10,28 @@ of the Mermaid source so unchanged diagrams are never re-fetched.
 When Kroki is unavailable (network error, HTTP error, timeout, or bad response)
 each affected diagram is left unchanged so the emitter falls back to a fenced
 code block.  The rest of the pipeline continues unaffected.
+
+Fallback behaviour
+------------------
+When the public ``https://kroki.io`` service returns a 504 (gateway timeout)
+for a Mermaid diagram, mk2conf automatically retries via ``mermaid.ink`` before
+giving up.  This fallback does **not** apply to self-hosted Kroki instances
+(configured as ``kroki:<url>``) — those run in isolation and should not reach
+out to external services.
 """
 
 from __future__ import annotations
 
+import base64
 import dataclasses
 import hashlib
+import json
 import sys
 import threading
 import time
 import urllib.error
 import urllib.request
+import zlib
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from typing import cast
@@ -30,7 +41,8 @@ from mkdocs_to_confluence.ir.treeutil import replace_nodes
 
 _CACHE_DIR = Path.home() / ".cache" / "mk2conf" / "mermaid"
 DEFAULT_KROKI_URL = "https://kroki.io"
-_TIMEOUT = 30  # seconds — fail fast when Kroki is down
+_MERMAID_INK_URL = "https://mermaid.ink"
+_TIMEOUT = 30  # seconds
 _MIN_PNG_BYTES = 67  # smallest valid PNG (1×1 px) is 67 bytes
 _CACHE_LOCK = threading.Lock()
 _MAX_WORKERS = 8
@@ -57,6 +69,21 @@ def _kroki_png(source: str, kroki_url: str) -> bytes:
         return cast(bytes, resp.read())
 
 
+def _mermaid_ink_png(source: str) -> bytes:
+    """Fetch a PNG rendering of *source* from mermaid.ink (GET, pako-encoded).
+
+    Encodes the diagram as ``{"code": source}`` compressed with zlib and
+    base64url-encoded — the pako format that mermaid.ink expects.
+    """
+    payload = json.dumps({"code": source, "mermaid": {"theme": "default"}}, separators=(",", ":"))
+    compressed = zlib.compress(payload.encode("utf-8"))
+    encoded = base64.urlsafe_b64encode(compressed).decode().rstrip("=")
+    url = f"{_MERMAID_INK_URL}/img/pako:{encoded}?type=png"
+    req = urllib.request.Request(url, headers={"User-Agent": "mk2conf/1.0"})
+    with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:  # noqa: S310  # nosec B310
+        return cast(bytes, resp.read())
+
+
 def _cache_path(source: str) -> Path:
     digest = hashlib.sha256(source.encode()).hexdigest()
     return _CACHE_DIR / f"mermaid_{digest}.png"
@@ -71,6 +98,11 @@ def _render_one(source: str, kroki_url: str, *, quiet: bool = False) -> Path | N
 
     Transient HTTP errors (429, 5xx) and network blips are retried up to
     ``_RETRY_ATTEMPTS`` times with exponential backoff.
+
+    When using the public kroki.io and all retries are exhausted due to kroki
+    being unreachable (504 or timeout), one final attempt is made via
+    mermaid.ink before giving up.  Self-hosted Kroki instances never fall back
+    to mermaid.ink.
     """
     path = _cache_path(source)
     if path.exists():
@@ -78,7 +110,10 @@ def _render_one(source: str, kroki_url: str, *, quiet: bool = False) -> Path | N
             print("        rendering  mermaid diagram (cached)")
         return path
 
+    use_public_kroki = kroki_url.rstrip("/") == DEFAULT_KROKI_URL.rstrip("/")
     last_exc: Exception | None = None
+    kroki_unavailable = False  # True when kroki is unreachable (504 or timeout)
+
     for attempt in range(_RETRY_ATTEMPTS):
         if attempt > 0:
             delay = _RETRY_BACKOFF * (2 ** (attempt - 1))
@@ -96,17 +131,34 @@ def _render_one(source: str, kroki_url: str, *, quiet: bool = False) -> Path | N
         except urllib.error.HTTPError as exc:
             if exc.code in _RETRYABLE_HTTP:
                 last_exc = exc
+                kroki_unavailable = exc.code == 504
                 continue  # retry
             _warn(f"mermaid diagram: Kroki returned HTTP {exc.code} {exc.reason} — falling back to code block")
             return None
         except urllib.error.URLError as exc:
             last_exc = exc
+            kroki_unavailable = True  # timeout or connection refused — kroki unreachable
             continue  # retry — network blip
         except (OSError, ValueError) as exc:
             _warn(f"mermaid diagram: {exc} — falling back to code block")
             return None
 
-    # All retries exhausted
+    # All Kroki retries exhausted — try mermaid.ink if on public kroki.io and kroki was unreachable.
+    if use_public_kroki and kroki_unavailable:
+        try:
+            _warn("mermaid diagram: kroki.io unreachable, trying mermaid.ink as fallback")
+            png = _mermaid_ink_png(source)
+            if len(png) < _MIN_PNG_BYTES:
+                raise ValueError(f"mermaid.ink returned {len(png)} bytes (expected a valid PNG)")
+            with _CACHE_LOCK:
+                path.write_bytes(png)
+            if not quiet:
+                print("        rendering  mermaid diagram (via mermaid.ink fallback)")
+            return path
+        except (urllib.error.URLError, urllib.error.HTTPError, OSError, ValueError) as exc:
+            _warn(f"mermaid diagram: mermaid.ink fallback also failed ({exc}) — falling back to code block")
+            return None
+
     _warn(f"mermaid diagram: failed after {_RETRY_ATTEMPTS} attempts ({last_exc}) — falling back to code block")
     return None
 
@@ -125,7 +177,10 @@ def render_mermaid_diagrams(
     upload as page attachments.
 
     Diagrams that fail to render are left unchanged (code-block fallback).
-    The pipeline always produces valid output regardless of Kroki availability.
+    When using public kroki.io and a diagram fails with a 504, one automatic
+    retry via mermaid.ink is attempted before falling back to a code block.
+    Self-hosted Kroki instances never contact mermaid.ink.
+    The pipeline always produces valid output regardless of service availability.
     """
     try:
         _CACHE_DIR.mkdir(parents=True, exist_ok=True)

{mkdocs2confluence-0.9.4 → mkdocs2confluence-0.9.6}/tests/test_mermaid.py

@@ -102,7 +102,7 @@ def test_render_deduplicates_identical_diagrams(tmp_path):
 
 
 def test_render_fallback_on_network_error(tmp_path, capsys):
-    """When Kroki is unreachable, node is left unchanged (code block fallback)."""
+    """When Kroki is unreachable and mermaid.ink also fails, node falls back to code block."""
     import urllib.error
 
     node = MermaidDiagram(source=_SAMPLE_SOURCE)
@@ -114,6 +114,10 @@ def test_render_fallback_on_network_error(tmp_path, capsys):
             "mkdocs_to_confluence.transforms.mermaid._kroki_png",
             side_effect=urllib.error.URLError("timed out"),
         ),
+        patch(
+            "mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+            side_effect=urllib.error.URLError("timed out"),
+        ),
     ):
         updated_nodes, attachments = render_mermaid_diagrams((node,))
 
@@ -218,7 +222,7 @@ def test_render_multiple_diagrams_concurrently(tmp_path):
 
 
 def test_render_one_failure_does_not_block_others(tmp_path):
-    """If one diagram fails, the rest still render successfully."""
+    """If one diagram fails (both kroki and mermaid.ink), the rest still render successfully."""
     import urllib.error
 
     good_source = "graph TD\n    A --> B\n"
@@ -231,7 +235,9 @@ def test_render_one_failure_does_not_block_others(tmp_path):
         return _FAKE_PNG
 
     with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
-         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png", side_effect=fake_kroki):
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png", side_effect=fake_kroki), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+               side_effect=urllib.error.URLError("timeout")):
         updated, attachments = render_mermaid_diagrams(nodes)
 
     # One attachment for the successful diagram
@@ -258,7 +264,7 @@ def test_render_one_cached(tmp_path):
 
 
 def test_render_one_network_failure_returns_none(tmp_path):
-    """_render_one returns None after all retries on persistent network failure."""
+    """_render_one returns None after all retries when both kroki and mermaid.ink fail."""
     import urllib.error
 
     from mkdocs_to_confluence.transforms.mermaid import _render_one
@@ -266,6 +272,8 @@ def test_render_one_network_failure_returns_none(tmp_path):
     with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
          patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
          patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.URLError("connection refused")), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
                side_effect=urllib.error.URLError("connection refused")):
         result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
 
@@ -365,3 +373,99 @@ def test_render_mermaid_cached_quiet_suppresses_stdout(tmp_path, capsys):
     assert result is not None
     out, _ = capsys.readouterr()
     assert out == ""
+
+
+# ── mermaid.ink fallback ──────────────────────────────────────────────────────
+
+
+def test_render_one_504_on_public_kroki_falls_back_to_mermaid_ink(tmp_path, capsys):
+    """Public kroki.io 504 → automatic fallback to mermaid.ink."""
+    import urllib.error
+
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.HTTPError("url", 504, "Gateway Timeout", {}, None)), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+               return_value=_FAKE_PNG) as mock_ink:
+        result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
+
+    assert result is not None
+    assert result.exists()
+    mock_ink.assert_called_once_with(_SAMPLE_SOURCE)
+
+
+def test_render_one_timeout_on_public_kroki_falls_back_to_mermaid_ink(tmp_path):
+    """Public kroki.io timeout → automatic fallback to mermaid.ink."""
+    import urllib.error
+
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.URLError("timed out")), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+               return_value=_FAKE_PNG) as mock_ink:
+        result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
+
+    assert result is not None
+    assert result.exists()
+    mock_ink.assert_called_once_with(_SAMPLE_SOURCE)
+
+
+def test_render_one_504_on_self_hosted_kroki_does_not_fall_back(tmp_path):
+    """Self-hosted Kroki 504 → no mermaid.ink fallback (privacy isolation)."""
+    import urllib.error
+
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.HTTPError("url", 504, "Gateway Timeout", {}, None)), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+               return_value=_FAKE_PNG) as mock_ink:
+        result = _render_one(_SAMPLE_SOURCE, "https://my-internal-kroki.corp")
+
+    assert result is None
+    mock_ink.assert_not_called()
+
+
+def test_render_one_timeout_on_self_hosted_kroki_does_not_fall_back(tmp_path):
+    """Self-hosted Kroki timeout → no mermaid.ink fallback (privacy isolation)."""
+    import urllib.error
+
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.URLError("timed out")), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+               return_value=_FAKE_PNG) as mock_ink:
+        result = _render_one(_SAMPLE_SOURCE, "https://my-internal-kroki.corp")
+
+    assert result is None
+    mock_ink.assert_not_called()
+
+
+def test_render_one_mermaid_ink_fallback_also_fails_returns_none(tmp_path, capsys):
+    """When mermaid.ink fallback also fails, returns None (code-block fallback)."""
+    import urllib.error
+
+    from mkdocs_to_confluence.transforms.mermaid import _render_one
+
+    with patch("mkdocs_to_confluence.transforms.mermaid._CACHE_DIR", tmp_path), \
+         patch("mkdocs_to_confluence.transforms.mermaid.time.sleep"), \
+         patch("mkdocs_to_confluence.transforms.mermaid._kroki_png",
+               side_effect=urllib.error.HTTPError("url", 504, "Gateway Timeout", {}, None)), \
+         patch("mkdocs_to_confluence.transforms.mermaid._mermaid_ink_png",
+               side_effect=urllib.error.URLError("connection refused")):
+        result = _render_one(_SAMPLE_SOURCE, "https://kroki.io")
+
+    assert result is None
+    _, err = capsys.readouterr()
+    assert "mermaid.ink" in err