markdown-to-confluence 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

{markdown_to_confluence-0.5.1.dist-info → markdown_to_confluence-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.1
+Version: 0.5.3
 Summary: Publish Markdown files to Confluence wiki
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -27,18 +27,18 @@ Requires-Dist: cattrs>=25.3
 Requires-Dist: lxml>=6.0
 Requires-Dist: markdown>=3.10
 Requires-Dist: orjson>=3.11
-Requires-Dist: pymdown-extensions>=10.17
+Requires-Dist: pymdown-extensions>=10.19
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: requests>=2.32
 Requires-Dist: truststore>=0.10
 Requires-Dist: typing-extensions>=4.15; python_version < "3.12"
 Provides-Extra: dev
-Requires-Dist: markdown_doc>=0.1.5; extra == "dev"
-Requires-Dist: types-lxml>=2025.8.25; extra == "dev"
+Requires-Dist: markdown_doc>=0.1.6; extra == "dev"
+Requires-Dist: types-lxml>=2025.11.25; extra == "dev"
 Requires-Dist: types-markdown>=3.10; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Requires-Dist: types-requests>=2.32; extra == "dev"
-Requires-Dist: mypy>=1.18; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
 Requires-Dist: ruff>=0.14; extra == "dev"
 Provides-Extra: formulas
 Requires-Dist: matplotlib>=3.9; extra == "formulas"
@@ -98,6 +98,15 @@ pip install markdown-to-confluence
 npm install -g @mermaid-js/mermaid-cli
 ```
 
+**Optional.** Pre-rendering PlantUML diagrams into PNG or SVG images requires Java, Graphviz and [PlantUML](https://plantuml.com/). (Refer to `--render-plantuml`.)
+
+1. **Install Java**: Version 8 or later from [Adoptium](https://adoptium.net/) or [Oracle](https://www.oracle.com/java/technologies/downloads/)
+2. **Install Graphviz**: Required for most diagram types in PlantUML (except sequence diagrams)
+   * **Ubuntu/Debian**: `sudo apt-get install Graphviz`
+   * **macOS**: `brew install graphviz`
+   * **Windows**: Download from [graphviz.org](https://graphviz.org/download/)
+3. **Download PlantUML JAR**: Download [plantuml.jar](https://github.com/plantuml/plantuml/releases) and set `PLANTUML_JAR` environment variable to point to it
+
 **Optional.** Converting formulas and equations to PNG or SVG images requires [Matplotlib](https://matplotlib.org/):
 
 ```sh
@@ -112,7 +121,11 @@ As authors of *md2conf*, we don't endorse or support any particular Confluence m
 
 **Optional.** Displaying Mermaid diagrams in Confluence without pre-rendering in the synchronization phase requires a [marketplace app](https://marketplace.atlassian.com/apps/1226567/mermaid-diagrams-for-confluence). (Refer to `--no-render-mermaid`.)
 
-**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/).
+**Optional.** PlantUML diagrams are embedded with compressed source data and are displayed using the [PlantUML Diagrams for Confluence](https://marketplace.atlassian.com/apps/1215115/plantuml-diagrams-for-confluence) app (if installed). (Refer to `--no-render-plantuml`.)
+
+Installing `plantuml.jar` (see above) helps display embedded diagrams with pre-calculated optimal dimensions.
+
+**Optional.** Displaying formulas and equations in Confluence requires [marketplace app](https://marketplace.atlassian.com/apps/1226109/latex-math-for-confluence-math-formula-equations), refer to [LaTeX Math for Confluence - Math Formula & Equations](https://help.narva.net/latex-math-for-confluence/). (Refer to `--no-render-latex`.)
 
 ## Getting started
 
@@ -215,6 +228,21 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+The generated-by text can also be templated with the following variables:
+
+- `%{filename}`: the name of the Markdown file
+- `%{filestem}`: the name of the Markdown file without the extension
+- `%{filepath}`: the path of the Markdown file relative to the _source root_
+- `%{filedir}`: the dirname of the `%{filepath}` (the path without the filename)
+
+When publishing a directory hierarchy, the *source root* is the directory in which *md2conf* is launched. When publishing a single file, this is the directory in which the Markdown file resides.
+
+It can be used with the CLI `--generated-by` option or directly in the files:
+
+```markdown
+<!-- generated-by: Do not edit! Check out the file %{filepath} in the repo -->
+```
+
 ### Publishing a single page
 
 *md2conf* has two modes of operation: *single-page mode* and *directory mode*.
@@ -359,6 +387,11 @@ Likewise, if you have a nested list, make sure that nested items are indented by
 
 Local images referenced in a Markdown file are automatically published to Confluence as attachments to the page.
 
+* Relative paths (e.g. `path/to/image.png` or `../to/image.png`) resolve to absolute paths w.r.t. the Markdown document location.
+* Absolute paths (e.g. `/path/to/image.png`) are interpreted w.r.t. to the synchronization root (typically the shell current directory).
+
+As a security measure, resolved paths can only reference files that are in the directory hierarchy of the synchronization root; you can't use `..` to leave the top-level directory of the synchronization root.
+
 Unfortunately, Confluence struggles with SVG images, e.g. they may only show in *edit* mode, display in a wrong size or text labels in the image may be truncated. (This seems to be a known issue in Confluence.) In order to mitigate the issue, whenever *md2conf* encounters a reference to an SVG image in a Markdown file, it checks whether a corresponding PNG image also exists in the same directory, and if a PNG image is found, it is published instead.
 
 External images referenced with an absolute URL retain the original URL.
@@ -455,6 +488,58 @@ This is useful if you have a page in a hierarchy that participates in parent-chi
 
 If the `title` attribute (in the front-matter) or the topmost unique heading (in the document body) changes, the Confluence page title is updated. A warning is raised if the new title conflicts with the title of another page, and thus cannot be updated.
 
+#### Avoiding duplicate titles
+
+By default, when *md2conf* extracts a page title from the first unique heading in a Markdown document, the heading remains in the document body. This means the title appears twice on the Confluence page: once as the page title at the top, and once as the first heading in the content.
+
+To avoid this duplication, use the `--skip-title-heading` option. When enabled, *md2conf* removes the first heading from the document body if it was used as the page title. This option only takes effect when:
+
+1. The title was extracted from the document's first unique heading (not from front-matter), AND
+2. There is exactly one top-level heading in the document.
+
+If the title comes from the `title` attribute in front-matter, the heading is preserved in the document body regardless of this setting, as the heading and title are considered separate.
+
+**Example without `--skip-title-heading` (default):**
+
+Markdown:
+```markdown
+# Installation Guide
+
+Follow these steps...
+```
+
+Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts with heading "Installation Guide", followed by "Follow these steps..."
+
+**Example with `--skip-title-heading`:**
+
+Same Markdown source, but Confluence displays:
+- Page title: "Installation Guide"
+- Content: Starts directly with "Follow these steps..." (heading removed)
+
+**Edge case: Abstract or introductory text before the title:**
+
+When a document has content before the first heading (like an abstract), removing the heading eliminates the visual separator between the introductory text and the main content:
+
+```markdown
+This is an abstract paragraph providing context.
+
+# Document Title
+
+This is the main document content.
+```
+
+With `--skip-title-heading`, the output becomes:
+- Page title: "Document Title"
+- Content: "This is an abstract paragraph..." flows directly into "This is the main document content..." (no heading separator)
+
+While the structure remains semantically correct, the visual separation is lost. If you need to maintain separation, consider these workarounds:
+
+1. **Use a horizontal rule:** Add `---` after the abstract to create visual separation
+2. **Use an admonition block:** Wrap the abstract in an info/note block
+3. **Use front-matter title:** Set `title` in front-matter to keep the heading in the body
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -540,7 +625,9 @@ Specifically, image references for status labels (e.g. `![My label][STATUS-RED]`
 
 ### Running the tool
 
-You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
+#### Command line
+
+You can synchronize a (directory of) Markdown file(s) with Confluence using the command-line tool `md2conf`:
 
 ```sh
 $ python3 -m md2conf sample/index.md
@@ -571,27 +658,89 @@ options:
   -r ROOT_PAGE          Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.
   --keep-hierarchy      Maintain source directory structure when exporting to Confluence.
   --flatten-hierarchy   Flatten directories with no index.md or README.md when exporting to Confluence.
-  --generated-by GENERATED_BY
+  --generated-by MARKDOWN
                         Add prompt to pages (default: 'This page has been generated with a tool.').
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.
   --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.)
   --no-render-drawio    Upload draw.io diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.)
   --no-render-mermaid   Upload Mermaid diagram sources as Confluence page attachments. (Marketplace app required to display.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.)
+  --no-render-plantuml  Upload PlantUML diagram sources as Confluence page attachments. (Marketplace app required to display.)
   --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.)
   --no-render-latex     Inline LaTeX formulas in Confluence page. (Marketplace app required to display.)
   --diagram-output-format {png,svg}
                         Format for rendering Mermaid and draw.io diagrams (default: 'png').
+  --prefer-raster       Prefer PNG over SVG when both exist (default: enabled).
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --no-heading-anchors  Don't place an anchor at each section heading.
   --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
-  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
-  --headers KEY=VALUE [KEY=VALUE ...]
-                        Apply custom headers to all Confluence API requests.
+  --skip-title-heading  Skip the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --no-skip-title-heading
+                        Keep the first heading in document body even when used as page title (default).
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
   --webui-links         Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)
   --alignment {center,left,right}
                         Alignment for block-level images and formulas (default: 'center').
+  --max-image-width MAX_IMAGE_WIDTH
+                        Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers KEY=VALUE [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
+```
+
+#### Python
+
+*md2conf* has a Python interface. Create a `ConnectionProperties` object to set connection parameters to the Confluence server, and a `DocumentOptions` object to configure how Markdown files are converted into pages on a Confluence wiki site. Open a connection to the Confluence server with the context manager `ConfluenceAPI`, and instantiate a `Publisher` to start converting documents.
+
+```python
+from md2conf.api import ConfluenceAPI
+from md2conf.environment import ConnectionProperties
+from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.publisher import Publisher
+
+properties = ConnectionProperties(
+    api_url=...,
+    domain=...,
+    base_path=...,
+    user_name=...,
+    api_key=...,
+    space_key=...,
+    headers=...,
+)
+options = DocumentOptions(
+    root_page_id=...,
+    keep_hierarchy=...,
+    title_prefix=...,
+    generated_by=...,
+    converter=ConverterOptions(
+        heading_anchors=...,
+        ignore_invalid_url=...,
+        skip_title_heading=...,
+        prefer_raster=...,
+        render_drawio=...,
+        render_mermaid=...,
+        render_plantuml=...,
+        render_latex=...,
+        diagram_output_format=...,
+        webui_links=...,
+        use_panel=...,
+        layout=LayoutOptions(
+            image=ImageLayoutOptions(
+                alignment=...,
+                max_width=...,
+            ),
+            table=TableLayoutOptions(
+                width=...,
+                display_mode=...,
+            ),
+        ),
+    ),
+)
+with ConfluenceAPI(properties) as api:
+    Publisher(api, options).process(mdpath)
 ```
 
 ### Confluence REST API v1 vs. v2

markdown_to_confluence-0.5.3.dist-info/RECORD

@@ -0,0 +1,55 @@
+markdown_to_confluence-0.5.3.dist-info/licenses/LICENSE,sha256=SEEBf2BMI1LUHnDvyHnV6L12A6zTAOQcsyMvaawAXWo,1077
+md2conf/__init__.py,sha256=CqQHkYFE1AAs4GhMm1nConbt3V7wksgDXzqm5mg6F6I,402
+md2conf/__main__.py,sha256=Wxz6Rx1Sx_J0FbaCY2HpByHqTMbxDEs1v5VzfdQh32U,13891
+md2conf/api.py,sha256=GVPElSP9qILA5IaEvtKaxjsoRQSsGMMoRhCxjjzLadM,42703
+md2conf/attachment.py,sha256=Nc3qGDENWBnsI6OVwMLXnk0EyEITpvov9MluDFD90ZI,1689
+md2conf/coalesce.py,sha256=YHnqFwow5wCj6OQ3oosig01D2lxWusAScMF4HAUO2-g,1305
+md2conf/collection.py,sha256=ukN74VCa4HaGSh6tLXpLd0j_UNPywcnKI0X7usgdSCo,824
+md2conf/compatibility.py,sha256=4ZNN6VLqxSbI1kowdsPproGZqwxBISys4Z22vBfe6Z8,687
+md2conf/converter.py,sha256=C6cROI8bUswyNZ1jSC0lf_9J-S6ojrXLbrkSDALuKR8,63065
+md2conf/csf.py,sha256=6H9G-5cZyyWMJr0tFskPNiWdQ2Ehq-V8EhlvvxhukWY,6582
+md2conf/emoticon.py,sha256=0g4rkx3d58xU4nnLak5ms7i0FSDnq0WJrLVFRgGyLC8,542
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/environment.py,sha256=TfNEz3Pyw9qe7f8i7e_kph16c09fhZ4cLNZZzIjmI18,3892
+md2conf/extension.py,sha256=5d2CtfULwiqlqwpOqbvlVu2KQ-kVBkDDYAhnHXbq79I,2227
+md2conf/external.py,sha256=ZRL0mCY02Gp4XfqRdbap2YdOihSpY2LA6tdGJBfC-FQ,1693
+md2conf/formatting.py,sha256=ygL59VgpioX069axEX-7XjKs0sUjTfIZiBE5fWmITxc,4557
+md2conf/frontmatter.py,sha256=iWtn_oXoLQxvCsdI3OXs1ylWGmB-gc7mMLpSGg113i4,1888
+md2conf/image.py,sha256=udlnUY_xOmI-PJAqWqXBF7hAO3pj_VW7u5hXhBw4HcA,5260
+md2conf/latex.py,sha256=haZKkUxSEcPj3fVmiIVZAwgszqNqGLk1GQ7i8KGHpo0,2226
+md2conf/local.py,sha256=eY3WpY-lNzLZeAfxX1ACVEhuzz0HDYX_sNQogJfkqcM,3673
+md2conf/markdown.py,sha256=4Km-AbQH04nDgPF0ijo-Ld7o8jTPXzENIMn7P1qIk0o,3148
+md2conf/matcher.py,sha256=Xg4YSb87iPkCzhKuKytBut6NOkEab3IM-AjzXbwy64U,6774
+md2conf/metadata.py,sha256=NOjbCIrwLgTIIeNgmo7w5JXuT-pxOXBGSg-irfdpokk,976
+md2conf/options.py,sha256=MJka7h0ly6D5QQNXEi9ios1uQbqHQpyn07XciHV-mF8,4385
+md2conf/png.py,sha256=wbo8tgm8Vxi56q5PLoTutZBU6qF73KJ6TJbs7G7LPG4,6166
+md2conf/processor.py,sha256=yqRb1Njn8XWxx22byq5nrobeH9AOp55mHTVoBUJlN2A,10203
+md2conf/publisher.py,sha256=6WfyZxWB59PrOro6wgkgXuFcnf7AqarlUfHo-Twzu9k,8509
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/scanner.py,sha256=wvh5IlD2VnAwulqY6PUe33k1D8Uag0kqTs9pQ-YFq8g,3736
+md2conf/serializer.py,sha256=W4_yLJfT3vLw0PUg88lpUEnvn64CjaX3ZaKgIrwcxfw,1786
+md2conf/svg.py,sha256=b98hxpVL-yFojln8NunxQRJSabMdfvazo7FkFySjALY,11054
+md2conf/text.py,sha256=cnYV_JQp_v91LbQHo3qvxcEuhIdaPjCjkmLOKINcNv4,1736
+md2conf/toc.py,sha256=HCtnREEucmGfqzwq-Dk6Q4ZgxW5Z8nZk6lg8UfhcoI0,2413
+md2conf/uri.py,sha256=my0deyR5SlppJrYCbXF1Zz94QA1JT-HTWe9pKw7AJ_A,1158
+md2conf/xml.py,sha256=uaaUDs0hfluNX74dfkY_Dxu1KmeNDGogpGRGpUVEfE4,5526
+md2conf/drawio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/drawio/extension.py,sha256=-k0pAhIZXDjiKeHlTJl2MGWMYpG-PmXK91-_vBMQZnE,4389
+md2conf/drawio/render.py,sha256=veSu5gjm5ggLnmaH7uvH9qNeOygBJpqhSKK_LJs0QTk,8581
+md2conf/mermaid/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/mermaid/config.py,sha256=5Dec2QcdB_GtnuXIW6nhJK8J5caduNZU1oz1mcmmb44,376
+md2conf/mermaid/extension.py,sha256=1drXVM_KbS00dcjSCRru0wwbil4zq3aR81dHMhfe7zA,4021
+md2conf/mermaid/render.py,sha256=cGq3hOemgsbh6btt7uJaRxzH4EmGis0K6_qNW5YrhIk,1834
+md2conf/mermaid/scanner.py,sha256=oIpaNxiZBNcmggnjlyYGcIVOXcYQWjf1lEVdyIwE4xE,1379
+md2conf/plantuml/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+md2conf/plantuml/config.py,sha256=j0ONhkzmAPagh00ltamTKlVEvXa6R284We9pDxRy-5U,378
+md2conf/plantuml/extension.py,sha256=-WEL6Ssa3Kz_7D_AQSnB1da0bylyYZivmRQwlOBfYcM,6281
+md2conf/plantuml/render.py,sha256=fwwKJIv_q1Fm9Vd8af7OcEG-5MkojZ-fxrQgA33grE8,3818
+md2conf/plantuml/scanner.py,sha256=Oso6VbHVuMaPMKMazQc_bf4hhOT5WeJN5WiVPM8peyM,1347
+markdown_to_confluence-0.5.3.dist-info/METADATA,sha256=7r3TveKAaJPBk14SGcJHuCXuDYD0rt7KUK6a_A8p1gE,43775
+markdown_to_confluence-0.5.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+markdown_to_confluence-0.5.3.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.5.3.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.5.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.5.3.dist-info/RECORD,,

{markdown_to_confluence-0.5.1.dist-info → markdown_to_confluence-0.5.3.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2025 Levente Hunyadi
+Copyright (c) 2022-2026 Levente Hunyadi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

md2conf/__init__.py

@@ -5,9 +5,9 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2022-2025, Levente Hunyadi"
+__copyright__ = "Copyright 2022-2026, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"

md2conf/__main__.py

@@ -4,7 +4,7 @@ Publish Markdown files to Confluence wiki.
 Parses Markdown files, converts Markdown content into the Confluence Storage Format (XHTML), and invokes
 Confluence API endpoints to upload images and content.
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2022-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -19,10 +19,10 @@ from pathlib import Path
 from typing import Any, Iterable, Literal, Sequence
 
 from . import __version__
-from .domain import ConfluenceDocumentOptions, ConfluencePageID
-from .environment import ArgumentError, ConfluenceConnectionProperties, ConfluenceSiteProperties
-from .extra import override
+from .compatibility import override
+from .environment import ArgumentError, ConfluenceSiteProperties, ConnectionProperties
 from .metadata import ConfluenceSiteMetadata
+from .options import ConfluencePageID, ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions
 
 
 class Arguments(argparse.Namespace):
@@ -34,19 +34,24 @@ class Arguments(argparse.Namespace):
     api_key: str | None
     space: str | None
     loglevel: str
-    ignore_invalid_url: bool
     heading_anchors: bool
+    ignore_invalid_url: bool
     root_page: str | None
     keep_hierarchy: bool
+    skip_title_heading: bool
+    title_prefix: str | None
     generated_by: str | None
+    prefer_raster: bool
     render_drawio: bool
     render_mermaid: bool
+    render_plantuml: bool
     render_latex: bool
     diagram_output_format: Literal["png", "svg"]
     local: bool
     headers: dict[str, str]
     webui_links: bool
     alignment: Literal["center", "left", "right"]
+    max_image_width: int | None
     use_panel: bool
 
 
@@ -151,6 +156,7 @@ def get_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--generated-by",
         default="This page has been generated with a tool.",
+        metavar="MARKDOWN",
         help="Add prompt to pages (default: 'This page has been generated with a tool.').",
     )
     parser.add_argument(
@@ -186,6 +192,19 @@ def get_parser() -> argparse.ArgumentParser:
         action="store_false",
         help="Upload Mermaid diagram sources as Confluence page attachments. (Marketplace app required to display.)",
     )
+    parser.add_argument(
+        "--render-plantuml",
+        dest="render_plantuml",
+        action="store_true",
+        default=True,
+        help="Render PlantUML diagrams as image files. (Installed utility required to convert.)",
+    )
+    parser.add_argument(
+        "--no-render-plantuml",
+        dest="render_plantuml",
+        action="store_false",
+        help="Upload PlantUML diagram sources as Confluence page attachments. (Marketplace app required to display.)",
+    )
     parser.add_argument(
         "--render-latex",
         dest="render_latex",
@@ -206,6 +225,19 @@ def get_parser() -> argparse.ArgumentParser:
         default="png",
         help="Format for rendering Mermaid and draw.io diagrams (default: 'png').",
     )
+    parser.add_argument(
+        "--prefer-raster",
+        dest="prefer_raster",
+        action="store_true",
+        default=True,
+        help="Prefer PNG over SVG when both exist (default: enabled).",
+    )
+    parser.add_argument(
+        "--no-prefer-raster",
+        dest="prefer_raster",
+        action="store_false",
+        help="Use SVG files directly instead of preferring PNG equivalents.",
+    )
     parser.add_argument(
         "--heading-anchors",
         action="store_true",
@@ -225,18 +257,22 @@ def get_parser() -> argparse.ArgumentParser:
         help="Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.",
     )
     parser.add_argument(
-        "--local",
+        "--skip-title-heading",
         action="store_true",
         default=False,
-        help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
+        help="Skip the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).",
     )
     parser.add_argument(
-        "--headers",
-        nargs="+",
-        required=False,
-        action=KwargsAppendAction,
-        metavar="KEY=VALUE",
-        help="Apply custom headers to all Confluence API requests.",
+        "--no-skip-title-heading",
+        dest="skip_title_heading",
+        action="store_false",
+        help="Keep the first heading in document body even when used as page title (default).",
+    )
+    parser.add_argument(
+        "--title-prefix",
+        default=None,
+        metavar="TEXT",
+        help="String to prepend to Confluence page title for each published page.",
     )
     parser.add_argument(
         "--webui-links",
@@ -251,12 +287,33 @@ def get_parser() -> argparse.ArgumentParser:
         default="center",
         help="Alignment for block-level images and formulas (default: 'center').",
     )
+    parser.add_argument(
+        "--max-image-width",
+        dest="max_image_width",
+        type=int,
+        default=None,
+        help="Maximum display width for images [px]. Wider images are scaled down for page display. Original size kept for full-size viewing.",
+    )
     parser.add_argument(
         "--use-panel",
         action="store_true",
         default=False,
         help="Transform admonitions and alerts into a Confluence custom panel.",
     )
+    parser.add_argument(
+        "--local",
+        action="store_true",
+        default=False,
+        help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
+    )
+    parser.add_argument(
+        "--headers",
+        nargs="+",
+        required=False,
+        action=KwargsAppendAction,
+        metavar="KEY=VALUE",
+        help="Apply custom headers to all Confluence API requests.",
+    )
     return parser
 
 
@@ -279,19 +336,30 @@ def main() -> None:
         format="%(asctime)s - %(levelname)s - %(funcName)s [%(lineno)d] - %(message)s",
     )
 
-    options = ConfluenceDocumentOptions(
-        heading_anchors=args.heading_anchors,
-        ignore_invalid_url=args.ignore_invalid_url,
-        generated_by=args.generated_by,
+    options = DocumentOptions(
         root_page_id=ConfluencePageID(args.root_page) if args.root_page else None,
         keep_hierarchy=args.keep_hierarchy,
-        render_drawio=args.render_drawio,
-        render_mermaid=args.render_mermaid,
-        render_latex=args.render_latex,
-        diagram_output_format=args.diagram_output_format,
-        webui_links=args.webui_links,
-        alignment=args.alignment,
-        use_panel=args.use_panel,
+        title_prefix=args.title_prefix,
+        generated_by=args.generated_by,
+        converter=ConverterOptions(
+            heading_anchors=args.heading_anchors,
+            ignore_invalid_url=args.ignore_invalid_url,
+            skip_title_heading=args.skip_title_heading,
+            prefer_raster=args.prefer_raster,
+            render_drawio=args.render_drawio,
+            render_mermaid=args.render_mermaid,
+            render_plantuml=args.render_plantuml,
+            render_latex=args.render_latex,
+            diagram_output_format=args.diagram_output_format,
+            webui_links=args.webui_links,
+            use_panel=args.use_panel,
+            layout=LayoutOptions(
+                image=ImageLayoutOptions(
+                    alignment=args.alignment,
+                    max_width=args.max_image_width,
+                ),
+            ),
+        ),
     )
     if args.local:
         from .local import LocalConverter
@@ -317,7 +385,7 @@ def main() -> None:
         from .publisher import Publisher
 
         try:
-            properties = ConfluenceConnectionProperties(
+            properties = ConnectionProperties(
                 api_url=args.api_url,
                 domain=args.domain,
                 base_path=args.path,
@@ -330,10 +398,7 @@ def main() -> None:
             parser.error(str(e))
         try:
             with ConfluenceAPI(properties) as api:
-                Publisher(
-                    api,
-                    options,
-                ).process(args.mdpath)
+                Publisher(api, options).process(args.mdpath)
         except HTTPError as err:
             logging.error(err)