markdown-to-confluence 0.5.4__tar.gz → 0.5.5__tar.gz

{markdown_to_confluence-0.5.4 → markdown_to_confluence-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-to-confluence
-Version: 0.5.4
+Version: 0.5.5
 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.19
+Requires-Dist: pymdown-extensions>=10.20
 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"
+Requires-Dist: typing-extensions>=4.15; python_version < "3.11"
 Provides-Extra: dev
-Requires-Dist: markdown_doc>=0.1.6; extra == "dev"
-Requires-Dist: types-lxml>=2025.11.25; extra == "dev"
+Requires-Dist: markdown_doc>=0.1.7; extra == "dev"
+Requires-Dist: types-lxml>=2026.1.1; 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.19; extra == "dev"
+Requires-Dist: mypy[faster-cache]>=1.19; extra == "dev"
 Requires-Dist: ruff>=0.14; extra == "dev"
 Provides-Extra: formulas
 Requires-Dist: matplotlib>=3.9; extra == "formulas"
@@ -612,6 +612,35 @@ This Markdown document is neither parsed, nor synchronized with Confluence.
 
 This is useful if you have a page in a hierarchy that participates in parent-child relationships but whose content is edited directly in Confluence. Specifically, these documents can be referenced with relative links from other Markdown documents in the file system tree.
 
+### Excluding content sections
+
+When maintaining documentation in both Git repositories and Confluence, you may want certain content to appear only in the repository but not on Confluence pages. Use HTML comment markers to wrap and exclude specific sections from synchronization:
+
+```markdown
+# Project Documentation
+
+This content appears in both Git and Confluence.
+
+<!-- confluence-skip-start -->
+## Internal References
+- See [internal design doc](../internal/design.md)
+- Related to issue #123
+- Development notes for the team
+<!-- confluence-skip-end -->
+
+## Getting Started
+This section is published to Confluence.
+```
+
+Content between `<!-- confluence-skip-start -->` and `<!-- confluence-skip-end -->` markers is removed before conversion and will not appear on the Confluence page. This is useful for:
+
+- Repository-specific navigation and cross-references
+- GitLab/GitHub-specific metadata
+- Content relevant only for developers with repository access
+
+Multiple exclusion blocks can be used in the same document.
+
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -681,36 +710,46 @@ options:
                         Use this option to set the log verbosity.
   -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.
+  --skip-hierarchy      Flatten directories with no `index.md` or `README.md` when exporting to Confluence.
   --generated-by MARKDOWN
-                        Add prompt to pages (default: 'This page has been generated with a tool.').
+                        Add prompt to pages.
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.
   --skip-update         Skip saving Confluence page ID in Markdown files.
-  --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.)
+  --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
+  --no-heading-anchors  Omit the extra anchor from section headings. (May break manually placed same-page references.) (default)
+  --force-valid-url     Raise an error when relative URLs point to an invalid location. (default)
+  --no-force-valid-url  Emit a warning but otherwise ignore relative URLs that point to an invalid location.
+  --skip-title-heading  Remove the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --keep-title-heading  Keep the first heading in document body even when used as page title. (default)
+  --prefer-raster       Prefer PNG over SVG when both exist. (default)
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
+  --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.) (default)
   --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.)
+  --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.) (default)
   --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.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.) (default)
   --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.)
+  --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.) (default)
   --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.
-  --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.
+                        Format for rendering Mermaid and draw.io diagrams. (default: png)
   --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.
+  --no-webui-links      Use hierarchical links including space and page ID. (default)
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --no-use-panel        Use standard Confluence macro types for admonitions and alerts (info, tip, note and warning). (default)
+  --layout-image-alignment {center,left,right,None}
+                        Alignment for block-level images and formulas.
+  --layout-image-max-width INT
+                        Maximum display width for images [px]. Wider images are scaled down for page display.
+  --layout-table-width INT
+                        Maximum table width in pixels.
+  --layout-table-display-mode {responsive,fixed}
+                        Set table display mode. (default: responsive)
+  --layout-alignment {center,left,right,None}
+                        Default alignment for block-level content.
+  --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
+  --line-numbers        Inject line numbers in Markdown source to help localize conversion errors.
   --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.
@@ -723,46 +762,49 @@ options:
 ```python
 from md2conf.api import ConfluenceAPI
 from md2conf.environment import ConnectionProperties
-from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.options import ConfluencePageID, ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
 from md2conf.publisher import Publisher
 
 properties = ConnectionProperties(
-    api_url=...,
-    domain=...,
-    base_path=...,
-    user_name=...,
-    api_key=...,
-    space_key=...,
-    headers=...,
+    domain=str() or None,
+    base_path=str() or None,
+    space_key=str() or None,
+    api_url=str() or None,
+    user_name=str() or None,
+    api_key=str(),
+    headers={str(): str()} or None,
 )
 options = DocumentOptions(
-    root_page_id=...,
-    keep_hierarchy=...,
-    title_prefix=...,
-    generated_by=...,
+    root_page_id=ConfluencePageID() or None,
+    keep_hierarchy=bool(),
+    title_prefix=str() or None,
+    generated_by=str() or None,
+    skip_update=bool(),
     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=...,
+        heading_anchors=bool(),
+        force_valid_url=bool(),
+        skip_title_heading=bool(),
+        prefer_raster=bool(),
+        render_drawio=bool(),
+        render_mermaid=bool(),
+        render_plantuml=bool(),
+        render_latex=bool(),
+        diagram_output_format='png' or 'svg',
+        webui_links=bool(),
+        use_panel=bool(),
         layout=LayoutOptions(
             image=ImageLayoutOptions(
-                alignment=...,
-                max_width=...,
+                alignment='center' or 'left' or 'right' or None,
+                max_width=int() or None,
             ),
             table=TableLayoutOptions(
-                width=...,
-                display_mode=...,
+                width=int() or None,
+                display_mode='responsive' or 'fixed',
             ),
+            alignment='center' or 'left' or 'right' or None,
         ),
     ),
+    line_numbers=bool(),
 )
 with ConfluenceAPI(properties) as api:
     Publisher(api, options).process(mdpath)

markdown_to_confluence-0.5.4/markdown_to_confluence.egg-info/PKG-INFO → markdown_to_confluence-0.5.5/README.md

@@ -1,49 +1,3 @@
-Metadata-Version: 2.4
-Name: markdown-to-confluence
-Version: 0.5.4
-Summary: Publish Markdown files to Confluence wiki
-Author-email: Levente Hunyadi <hunyadi@gmail.com>
-Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/hunyadi/md2conf
-Project-URL: Source, https://github.com/hunyadi/md2conf
-Keywords: markdown,converter,confluence
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Environment :: Console
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-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.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.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.19; extra == "dev"
-Requires-Dist: ruff>=0.14; extra == "dev"
-Provides-Extra: formulas
-Requires-Dist: matplotlib>=3.9; extra == "formulas"
-Dynamic: license-file
-
 # Publish Markdown files to Confluence wiki
 
 Contributors to software projects typically write documentation in Markdown format and host Markdown files in collaborative version control systems (VCS) such as GitHub or GitLab to track changes and facilitate the review process. However, not everyone at a company has access to VCS, and documents are often circulated in Confluence wiki instead.
@@ -612,6 +566,35 @@ This Markdown document is neither parsed, nor synchronized with Confluence.
 
 This is useful if you have a page in a hierarchy that participates in parent-child relationships but whose content is edited directly in Confluence. Specifically, these documents can be referenced with relative links from other Markdown documents in the file system tree.
 
+### Excluding content sections
+
+When maintaining documentation in both Git repositories and Confluence, you may want certain content to appear only in the repository but not on Confluence pages. Use HTML comment markers to wrap and exclude specific sections from synchronization:
+
+```markdown
+# Project Documentation
+
+This content appears in both Git and Confluence.
+
+<!-- confluence-skip-start -->
+## Internal References
+- See [internal design doc](../internal/design.md)
+- Related to issue #123
+- Development notes for the team
+<!-- confluence-skip-end -->
+
+## Getting Started
+This section is published to Confluence.
+```
+
+Content between `<!-- confluence-skip-start -->` and `<!-- confluence-skip-end -->` markers is removed before conversion and will not appear on the Confluence page. This is useful for:
+
+- Repository-specific navigation and cross-references
+- GitLab/GitHub-specific metadata
+- Content relevant only for developers with repository access
+
+Multiple exclusion blocks can be used in the same document.
+
+
 ### Labels
 
 If a Markdown document has the front-matter attribute `tags`, *md2conf* assigns the specified tags to the Confluence page as labels.
@@ -681,36 +664,46 @@ options:
                         Use this option to set the log verbosity.
   -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.
+  --skip-hierarchy      Flatten directories with no `index.md` or `README.md` when exporting to Confluence.
   --generated-by MARKDOWN
-                        Add prompt to pages (default: 'This page has been generated with a tool.').
+                        Add prompt to pages.
   --no-generated-by     Do not add 'generated by a tool' prompt to pages.
   --skip-update         Skip saving Confluence page ID in Markdown files.
-  --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.)
+  --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
+  --no-heading-anchors  Omit the extra anchor from section headings. (May break manually placed same-page references.) (default)
+  --force-valid-url     Raise an error when relative URLs point to an invalid location. (default)
+  --no-force-valid-url  Emit a warning but otherwise ignore relative URLs that point to an invalid location.
+  --skip-title-heading  Remove the first heading from document body when it is used as the page title (does not apply if title comes from front-matter).
+  --keep-title-heading  Keep the first heading in document body even when used as page title. (default)
+  --prefer-raster       Prefer PNG over SVG when both exist. (default)
+  --no-prefer-raster    Use SVG files directly instead of preferring PNG equivalents.
+  --render-drawio       Render draw.io diagrams as image files. (Installed utility required to covert.) (default)
   --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.)
+  --render-mermaid      Render Mermaid diagrams as image files. (Installed utility required to convert.) (default)
   --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.)
+  --render-plantuml     Render PlantUML diagrams as image files. (Installed utility required to convert.) (default)
   --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.)
+  --render-latex        Render LaTeX formulas as image files. (Matplotlib required to convert.) (default)
   --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.
-  --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.
+                        Format for rendering Mermaid and draw.io diagrams. (default: png)
   --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.
+  --no-webui-links      Use hierarchical links including space and page ID. (default)
   --use-panel           Transform admonitions and alerts into a Confluence custom panel.
+  --no-use-panel        Use standard Confluence macro types for admonitions and alerts (info, tip, note and warning). (default)
+  --layout-image-alignment {center,left,right,None}
+                        Alignment for block-level images and formulas.
+  --layout-image-max-width INT
+                        Maximum display width for images [px]. Wider images are scaled down for page display.
+  --layout-table-width INT
+                        Maximum table width in pixels.
+  --layout-table-display-mode {responsive,fixed}
+                        Set table display mode. (default: responsive)
+  --layout-alignment {center,left,right,None}
+                        Default alignment for block-level content.
+  --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
+  --title-prefix TEXT   String to prepend to Confluence page title for each published page.
+  --line-numbers        Inject line numbers in Markdown source to help localize conversion errors.
   --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.
@@ -723,46 +716,49 @@ options:
 ```python
 from md2conf.api import ConfluenceAPI
 from md2conf.environment import ConnectionProperties
-from md2conf.options import ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
+from md2conf.options import ConfluencePageID, ConverterOptions, DocumentOptions, ImageLayoutOptions, LayoutOptions, TableLayoutOptions
 from md2conf.publisher import Publisher
 
 properties = ConnectionProperties(
-    api_url=...,
-    domain=...,
-    base_path=...,
-    user_name=...,
-    api_key=...,
-    space_key=...,
-    headers=...,
+    domain=str() or None,
+    base_path=str() or None,
+    space_key=str() or None,
+    api_url=str() or None,
+    user_name=str() or None,
+    api_key=str(),
+    headers={str(): str()} or None,
 )
 options = DocumentOptions(
-    root_page_id=...,
-    keep_hierarchy=...,
-    title_prefix=...,
-    generated_by=...,
+    root_page_id=ConfluencePageID() or None,
+    keep_hierarchy=bool(),
+    title_prefix=str() or None,
+    generated_by=str() or None,
+    skip_update=bool(),
     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=...,
+        heading_anchors=bool(),
+        force_valid_url=bool(),
+        skip_title_heading=bool(),
+        prefer_raster=bool(),
+        render_drawio=bool(),
+        render_mermaid=bool(),
+        render_plantuml=bool(),
+        render_latex=bool(),
+        diagram_output_format='png' or 'svg',
+        webui_links=bool(),
+        use_panel=bool(),
         layout=LayoutOptions(
             image=ImageLayoutOptions(
-                alignment=...,
-                max_width=...,
+                alignment='center' or 'left' or 'right' or None,
+                max_width=int() or None,
             ),
             table=TableLayoutOptions(
-                width=...,
-                display_mode=...,
+                width=int() or None,
+                display_mode='responsive' or 'fixed',
             ),
+            alignment='center' or 'left' or 'right' or None,
         ),
     ),
+    line_numbers=bool(),
 )
 with ConfluenceAPI(properties) as api:
     Publisher(api, options).process(mdpath)