mkdocs2confluence 0.19.0__tar.gz → 0.20.0__tar.gz

{mkdocs2confluence-0.19.0/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.20.0}/PKG-INFO

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.19.0
+Version: 0.20.0
 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.19.0 → mkdocs2confluence-0.20.0}/src/mkdocs_to_confluence/cli.py

@@ -10,7 +10,7 @@ from pathlib import Path
 
 from mkdocs_to_confluence import __version__
 from mkdocs_to_confluence.compiler.page import compile_page
-from mkdocs_to_confluence.emitter.xhtml import configure_styles
+from mkdocs_to_confluence.emitter.xhtml import configure_admonitions, configure_styles
 from mkdocs_to_confluence.loader.config import load_config
 from mkdocs_to_confluence.loader.nav import find_section, find_section_by_folder, flat_pages, resolve_nav
 from mkdocs_to_confluence.loader.page import PageLoadError, find_page
@@ -340,6 +340,7 @@ def _cmd_preview(args: argparse.Namespace) -> None:
     config_path = Path(args.config).resolve()
     config = load_config(config_path)
     configure_styles(config.extra_styles)
+    configure_admonitions(config.confluence.admonitions if config.confluence else None)
 
     all_nodes = resolve_nav(config)
 
@@ -495,6 +496,7 @@ def _cmd_publish(args: argparse.Namespace) -> None:
     config_path = Path(args.config).resolve()
     config = load_config(config_path)
     configure_styles(config.extra_styles)
+    configure_admonitions(config.confluence.admonitions if config.confluence else None)
 
     conf_config = config.confluence
     if conf_config is None:
@@ -687,6 +689,7 @@ def _cmd_pdf(args: argparse.Namespace) -> None:
     config_path = Path(args.config).resolve()
     config = load_config(config_path)
     configure_styles(config.extra_styles)
+    configure_admonitions(config.confluence.admonitions if config.confluence else None)
 
     nodes = resolve_nav(config)
 

{mkdocs2confluence-0.19.0 → mkdocs2confluence-0.20.0}/src/mkdocs_to_confluence/emitter/xhtml.py

@@ -17,6 +17,7 @@ https://developer.atlassian.com/server/confluence/confluence-storage-format/
 from __future__ import annotations
 
 import html
+import sys
 from pathlib import Path
 from typing import Sequence
 
@@ -77,6 +78,32 @@ def configure_styles(styles: ExtraStyles | None) -> None:
     global _styles
     _styles = styles
 
+
+# ── Custom admonition aliases (set once per run via configure_admonitions) ─────
+
+_admonition_aliases: dict[str, str] = {}
+
+
+def configure_admonitions(aliases: dict[str, str] | None) -> None:
+    """Map custom admonition kinds onto built-in ones, from ``confluence.admonitions``.
+
+    Targets naming no built-in kind are kept but warned about — they resolve
+    through the same fallback as any unknown kind, so a typo degrades rather
+    than fails the build.
+    """
+    global _admonition_aliases
+    _admonition_aliases = dict(aliases or {})
+    unknown = sorted(
+        f"{k} -> {v}" for k, v in _admonition_aliases.items() if v not in _KNOWN_ADMONITION_KINDS
+    )
+    if unknown:
+        print(
+            "warning: confluence.admonitions targets an unknown admonition kind: "
+            + ", ".join(unknown)
+            + f". Known kinds: {', '.join(sorted(_KNOWN_ADMONITION_KINDS))}.",
+            file=sys.stderr,
+        )
+
 # ── Admonition kind → Confluence macro name ───────────────────────────────────
 
 # Types that map to Confluence's four native panel macros (include built-in icons).
@@ -106,6 +133,11 @@ _ADMONITION_MACRO: dict[str, str] = {
 _ADMONITION_DANGER_KINDS: frozenset[str] = frozenset(
     {"danger", "error", "bug", "failure", "fail", "missing"}
 )
+# Every kind the emitter understands as an alias target.
+_KNOWN_ADMONITION_KINDS: frozenset[str] = (
+    frozenset(_ADMONITION_MACRO) | _ADMONITION_DANGER_KINDS
+)
+
 _DANGER_EMOJI = "🚨"
 _DANGER_COLOURS = {
     "borderColor": "#DE350B",
@@ -350,8 +382,25 @@ def _emit_code_block(node: CodeBlock) -> str:
     return "".join(parts)
 
 
+def _resolve_admonition_kind(kind: str) -> str:
+    """Resolve *kind* to the built-in kind that decides its Confluence rendering.
+
+    Order: an explicit ``confluence.admonitions`` alias, then the built-in kinds,
+    then ``success`` for anything unrecognised.
+    """
+    alias = _admonition_aliases.get(kind)
+    if alias is not None:
+        return alias
+    if kind in _KNOWN_ADMONITION_KINDS:
+        return kind
+    return "success"
+
+
 def _emit_admonition(node: Admonition) -> str:
+    # The title keeps the author's own kind ("Value-driver"), only the styling
+    # follows the resolved kind.
     title = node.title or _DEFAULT_ADMONITION_TITLES.get(node.kind, node.kind.capitalize())
+    kind = _resolve_admonition_kind(node.kind)
     body = emit(node.children)
 
     # ??? and ???+ → Confluence expand macro (collapsible)
@@ -367,7 +416,7 @@ def _emit_admonition(node: Admonition) -> str:
 
     # Fall through for ???+ (expanded=True) — render as a regular admonition below.
 
-    if node.kind in _ADMONITION_DANGER_KINDS:
+    if kind in _ADMONITION_DANGER_KINDS:
         colours = "".join(
             f'  <ac:parameter ac:name="{k}">{v}</ac:parameter>\n'
             for k, v in _DANGER_COLOURS.items()
@@ -381,7 +430,7 @@ def _emit_admonition(node: Admonition) -> str:
             "</ac:structured-macro>\n"
         )
 
-    macro_name = _ADMONITION_MACRO.get(node.kind, "info")
+    macro_name = _ADMONITION_MACRO.get(kind, "tip")
     return (
         f'<ac:structured-macro ac:name="{macro_name}">\n'
         f'  <ac:parameter ac:name="title">{html.escape(title)}</ac:parameter>\n'

{mkdocs2confluence-0.19.0 → mkdocs2confluence-0.20.0}/src/mkdocs_to_confluence/loader/config.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlparse
@@ -38,6 +38,10 @@ class ConfluenceConfig:
     exclude_properties: tuple[str, ...] = ()  # front matter keys to omit from Page Properties table
     attachment_preview: bool = False  # render PDF/Office attachment links as view-file macros
     children_macro: bool = True  # append Children Display macro to section index pages
+    # Custom admonition kind → built-in kind it should render as, e.g.
+    # {"value-driver": "tip"}.  Kinds absent here fall back to the built-in
+    # mapping, then to "success".  Emitter owns the target vocabulary.
+    admonitions: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -314,6 +318,29 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
             )
         children_macro = raw_children
 
+        # admonitions (optional) — map custom admonition kinds onto built-in ones.
+        # Only the shape is checked here; the emitter owns the target vocabulary
+        # and warns about unknown targets, since loader sits below it in the layering.
+        raw_admonitions = raw_conf.get("admonitions", {})
+        if not isinstance(raw_admonitions, dict):
+            raise ConfigError(
+                "mkdocs.yml: 'confluence.admonitions' must be a mapping of "
+                f"custom kind to built-in kind, got {type(raw_admonitions).__name__}."
+            )
+        admonitions: dict[str, str] = {}
+        for key, value in raw_admonitions.items():
+            if not isinstance(key, str) or not key.strip():
+                raise ConfigError(
+                    "mkdocs.yml: 'confluence.admonitions' keys must be non-empty strings."
+                )
+            if not isinstance(value, str) or not value.strip():
+                raise ConfigError(
+                    f"mkdocs.yml: 'confluence.admonitions.{key}' must be a non-empty "
+                    "string naming a built-in admonition kind (e.g. 'tip', 'warning')."
+                )
+            # Admonition kinds are case-insensitive in Markdown; normalise both sides.
+            admonitions[key.strip().lower()] = value.strip().lower()
+
         confluence = ConfluenceConfig(
             base_url=base_url.rstrip("/"),
             space_key=space_key,
@@ -332,6 +359,7 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
             exclude_properties=exclude_properties,
             attachment_preview=attachment_preview,
             children_macro=children_macro,
+            admonitions=admonitions,
         )
 
     # --- extra_css (optional) ---

{mkdocs2confluence-0.19.0 → mkdocs2confluence-0.20.0}/src/mkdocs_to_confluence/parser/markdown.py

@@ -256,7 +256,7 @@ _FENCE_OPEN_RE = re.compile(r"^(?P<fence>`{3,}|~{3,})(?P<info>.*)$")
 
 # Matches an admonition opener:  !!! kind  /  !!! kind "title"  /  ??? kind  /  ???+ kind
 _ADMONITION_RE = re.compile(
-    r"""^[ ]{0,3}(?P<marker>!{3}|\?{3}\+?)\s+(?P<kind>\w+)(?:\s+(?P<q>["'])(?P<title>.*?)(?P=q))?\s*$"""
+    r"""^[ ]{0,3}(?P<marker>!{3}|\?{3}\+?)\s+(?P<kind>[\w-]+)(?:\s+(?P<q>["'])(?P<title>.*?)(?P=q))?\s*$"""
 )
 
 # Matches a Material for MkDocs content tab opener:  === "Label"

mkdocs2confluence-0.20.0/tests/test_admonition_titles.py

@@ -0,0 +1,118 @@
+"""Tests for the admonition-title link degradation transform."""
+
+from __future__ import annotations
+
+from mkdocs_to_confluence.ir.nodes import Admonition, Section, TextNode
+from mkdocs_to_confluence.transforms.admonition_titles import (
+    strip_links_in_admonition_titles,
+)
+
+
+def _adm(title: str | None) -> Admonition:
+    return Admonition(kind="warning", title=title, children=())
+
+
+def test_link_in_title_stripped_to_text() -> None:
+    nodes = (_adm("Conflict - see [Hello](foobar.md#hello)"),)
+    out = strip_links_in_admonition_titles(nodes, "index.md")
+    assert out[0].title == "Conflict - see Hello"
+
+
+def test_warning_emitted_with_page_and_title(capsys) -> None:
+    nodes = (_adm("see [Hello](foobar.md#hello)"),)
+    strip_links_in_admonition_titles(nodes, "guide/index.md")
+    err = capsys.readouterr().err
+    assert "warning" in err
+    assert "guide/index.md" in err
+    assert "see [Hello](foobar.md#hello)" in err
+
+
+def test_title_without_link_unchanged_and_no_warning(capsys) -> None:
+    nodes = (_adm("Just a plain title"),)
+    out = strip_links_in_admonition_titles(nodes, "index.md")
+    assert out[0].title == "Just a plain title"
+    assert capsys.readouterr().err == ""
+
+
+def test_none_title_is_safe(capsys) -> None:
+    nodes = (_adm(None),)
+    out = strip_links_in_admonition_titles(nodes, "index.md")
+    assert out[0].title is None
+    assert capsys.readouterr().err == ""
+
+
+def test_multiple_links_all_stripped() -> None:
+    nodes = (_adm("[A](a.md) and [B](b.md#x)"),)
+    out = strip_links_in_admonition_titles(nodes, "index.md")
+    assert out[0].title == "A and B"
+
+
+def test_nested_admonition_in_section_processed() -> None:
+    inner = _adm("see [Hello](foobar.md#hello)")
+    section = Section(level=2, anchor="s", title=(TextNode("S"),), children=(inner,))
+    out = strip_links_in_admonition_titles((section,), "index.md")
+    nested = out[0].children[0]
+    assert isinstance(nested, Admonition)
+    assert nested.title == "see Hello"
+
+
+def test_image_in_title_not_mangled() -> None:
+    nodes = (_adm("look ![alt](img.png)"),)
+    out = strip_links_in_admonition_titles(nodes, "index.md")
+    assert out[0].title == "look ![alt](img.png)"
+
+
+class TestCustomAdmonitionKinds:
+    """`confluence.admonitions` config, then built-ins, then a `success` default."""
+
+    def setup_method(self) -> None:
+        from mkdocs_to_confluence.emitter.xhtml import configure_admonitions
+        configure_admonitions(None)
+
+    teardown_method = setup_method
+
+    def _macro(self, src: str) -> str:
+        import re
+
+        from mkdocs_to_confluence.emitter.xhtml import emit
+        from mkdocs_to_confluence.parser import parse
+        m = re.search(r'ac:name="(\w+)"', emit(parse(src)))
+        return m.group(1) if m else ""
+
+    def test_hyphenated_kind_parses_as_an_admonition(self) -> None:
+        """`!!! value-driver` must not fall through to a paragraph."""
+        assert self._macro('!!! value-driver\n\n    Body.\n') != ""
+
+    def test_unknown_kind_defaults_to_success(self) -> None:
+        assert self._macro('!!! value-driver\n\n    Body.\n') == "tip"  # success -> tip
+
+    def test_builtin_kind_is_unaffected(self) -> None:
+        assert self._macro('!!! note\n\n    Body.\n') == "info"
+        assert self._macro('!!! warning\n\n    Body.\n') == "warning"
+
+    def test_config_alias_wins_over_the_default(self) -> None:
+        from mkdocs_to_confluence.emitter.xhtml import configure_admonitions
+        configure_admonitions({"value-driver": "warning"})
+        assert self._macro('!!! value-driver\n\n    Body.\n') == "warning"
+
+    def test_config_alias_can_target_a_danger_panel(self) -> None:
+        from mkdocs_to_confluence.emitter.xhtml import configure_admonitions
+        configure_admonitions({"risk": "danger"})
+        assert self._macro('!!! risk\n\n    Body.\n') == "panel"
+
+    def test_config_alias_can_override_a_builtin(self) -> None:
+        from mkdocs_to_confluence.emitter.xhtml import configure_admonitions
+        configure_admonitions({"note": "warning"})
+        assert self._macro('!!! note\n\n    Body.\n') == "warning"
+
+    def test_title_keeps_the_authors_kind_not_the_alias(self) -> None:
+        from mkdocs_to_confluence.emitter.xhtml import configure_admonitions, emit
+        from mkdocs_to_confluence.parser import parse
+        configure_admonitions({"value-driver": "warning"})
+        assert "Value-driver" in emit(parse('!!! value-driver\n\n    Body.\n'))
+
+    def test_unknown_alias_target_warns_and_degrades(self, capsys) -> None:  # type: ignore[no-untyped-def]
+        from mkdocs_to_confluence.emitter.xhtml import configure_admonitions
+        configure_admonitions({"oops": "nonsense"})
+        assert "unknown admonition kind" in capsys.readouterr().err
+        assert self._macro('!!! oops\n\n    Body.\n') == "tip"

{mkdocs2confluence-0.19.0 → mkdocs2confluence-0.20.0}/tests/test_publish_config.py

@@ -537,3 +537,45 @@ confluence:
     config = load_config(config_file)
     assert config.confluence is not None
     assert config.confluence.allow_any_host is False
+
+
+class TestAdmonitionsConfig:
+    """`confluence.admonitions` parsing and validation."""
+
+    def _write(self, tmp_path, block: str):  # type: ignore[no-untyped-def]
+        from mkdocs_to_confluence.loader.config import load_config
+        (tmp_path / "docs").mkdir(exist_ok=True)
+        (tmp_path / "mkdocs.yml").write_text(
+            "site_name: T\n"
+            "confluence:\n"
+            "  base_url: https://x.atlassian.net\n"
+            "  email: a@b.c\n"
+            "  token: t\n"
+            "  space_key: S\n" + block,
+            encoding="utf-8",
+        )
+        return load_config(tmp_path / "mkdocs.yml")
+
+    def test_absent_defaults_to_empty(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        cfg = self._write(tmp_path, "")
+        assert cfg.confluence is not None
+        assert cfg.confluence.admonitions == {}
+
+    def test_mapping_is_parsed_and_lowercased(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        cfg = self._write(tmp_path, "  admonitions:\n    Value-Driver: TIP\n    risk: danger\n")
+        assert cfg.confluence is not None
+        assert cfg.confluence.admonitions == {"value-driver": "tip", "risk": "danger"}
+
+    def test_non_mapping_is_rejected(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        import pytest
+
+        from mkdocs_to_confluence.loader.config import ConfigError
+        with pytest.raises(ConfigError, match="must be a mapping"):
+            self._write(tmp_path, "  admonitions:\n    - tip\n")
+
+    def test_non_string_value_is_rejected(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        import pytest
+
+        from mkdocs_to_confluence.loader.config import ConfigError
+        with pytest.raises(ConfigError, match="non-empty"):
+            self._write(tmp_path, "  admonitions:\n    risk: 5\n")

mkdocs2confluence-0.19.0/tests/test_admonition_titles.py

@@ -1,62 +0,0 @@
-"""Tests for the admonition-title link degradation transform."""
-
-from __future__ import annotations
-
-from mkdocs_to_confluence.ir.nodes import Admonition, Section, TextNode
-from mkdocs_to_confluence.transforms.admonition_titles import (
-    strip_links_in_admonition_titles,
-)
-
-
-def _adm(title: str | None) -> Admonition:
-    return Admonition(kind="warning", title=title, children=())
-
-
-def test_link_in_title_stripped_to_text() -> None:
-    nodes = (_adm("Conflict - see [Hello](foobar.md#hello)"),)
-    out = strip_links_in_admonition_titles(nodes, "index.md")
-    assert out[0].title == "Conflict - see Hello"
-
-
-def test_warning_emitted_with_page_and_title(capsys) -> None:
-    nodes = (_adm("see [Hello](foobar.md#hello)"),)
-    strip_links_in_admonition_titles(nodes, "guide/index.md")
-    err = capsys.readouterr().err
-    assert "warning" in err
-    assert "guide/index.md" in err
-    assert "see [Hello](foobar.md#hello)" in err
-
-
-def test_title_without_link_unchanged_and_no_warning(capsys) -> None:
-    nodes = (_adm("Just a plain title"),)
-    out = strip_links_in_admonition_titles(nodes, "index.md")
-    assert out[0].title == "Just a plain title"
-    assert capsys.readouterr().err == ""
-
-
-def test_none_title_is_safe(capsys) -> None:
-    nodes = (_adm(None),)
-    out = strip_links_in_admonition_titles(nodes, "index.md")
-    assert out[0].title is None
-    assert capsys.readouterr().err == ""
-
-
-def test_multiple_links_all_stripped() -> None:
-    nodes = (_adm("[A](a.md) and [B](b.md#x)"),)
-    out = strip_links_in_admonition_titles(nodes, "index.md")
-    assert out[0].title == "A and B"
-
-
-def test_nested_admonition_in_section_processed() -> None:
-    inner = _adm("see [Hello](foobar.md#hello)")
-    section = Section(level=2, anchor="s", title=(TextNode("S"),), children=(inner,))
-    out = strip_links_in_admonition_titles((section,), "index.md")
-    nested = out[0].children[0]
-    assert isinstance(nested, Admonition)
-    assert nested.title == "see Hello"
-
-
-def test_image_in_title_not_mangled() -> None:
-    nodes = (_adm("look ![alt](img.png)"),)
-    out = strip_links_in_admonition_titles(nodes, "index.md")
-    assert out[0].title == "look ![alt](img.png)"