markdown-to-confluence 0.2.7__py3-none-any.whl → 0.3.1__py3-none-any.whl

{markdown_to_confluence-0.2.7.dist-info → markdown_to_confluence-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: markdown-to-confluence
-Version: 0.2.7
+Version: 0.3.1
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -12,20 +12,20 @@ Classifier: Intended Audience :: End Users/Desktop
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 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: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: lxml>=5.3
-Requires-Dist: types-lxml>=2024.11.8
+Requires-Dist: types-lxml>=2024.12.13
 Requires-Dist: markdown>=3.7
 Requires-Dist: types-markdown>=3.7
-Requires-Dist: pymdown-extensions>=10.12
+Requires-Dist: pymdown-extensions>=10.14
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: types-PyYAML>=6.0
 Requires-Dist: requests>=2.32
@@ -57,6 +57,8 @@ This Python package
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
 * [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
 
+Whenever possible, the implementation uses [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/) to fetch space properties, and get, create or update page content.
+
 ## Installation
 
 Install the core package from PyPI:
@@ -160,6 +162,41 @@ First, *md2conf* builds an index of pages in the directory hierarchy. The index
 
 If a Markdown file doesn't yet pair up with a Confluence page, *md2conf* creates a new page and assigns a parent. Parent-child relationships are reflected in the navigation panel in Confluence. You can set a root page ID with the command-line option `-r`, which constitutes the topmost parent. (This could correspond to the landing page of your Confluence space. The Confluence page ID is always revealed when you edit a page.) Whenever a directory contains the file `index.md` or `README.md`, this page becomes the future parent page, and all Markdown files in this directory (and possibly nested directories) become its child pages (unless they already have a page ID). However, if an `index.md` or `README.md` file is subsequently found in one of the nested directories, it becomes the parent page of that directory, and any of its subdirectories.
 
+The concepts above are illustrated in the following sections.
+
+#### File-system directory hierarchy
+
+The title of each Markdown file (either the text of the first heading (`#`), or the title specified in front-matter) is shown next to the file name.
+
+```
+.
+├── computer-science
+│   ├── index.md: Introduction to computer science
+│   ├── algebra.md: Linear algebra
+│   └── algorithms.md: Theory of algorithms
+└── machine-learning
+    ├── README.md: AI and ML
+    ├── awareness.md: Consciousness and intelligence
+    └── statistics
+        ├── index.md: Introduction to statistics
+        └── median.md: Mean vs. median
+```
+
+#### Page hierarchy in Confluence
+
+Observe how `index.md` and `README.md` files have assumed parent (or ancestor) role for any Markdown files in the same directory (or below).
+
+```
+root
+├── Introduction to computer science
+│   ├── Linear algebra
+│   └── Theory of algorithms
+└── AI and ML
+    ├── Consciousness and intelligence
+    └── Introduction to statistics
+        └── Mean vs. median
+```
+
 ### Ignoring files
 
 Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
@@ -214,7 +251,7 @@ options:
   --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
   --headers [KEY=VALUE ...]
                         Apply custom headers to all Confluence API requests.
-  --webui-links         Enable Confluence Web UI links.
+  --webui-links         Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)
 ```
 
 ### Using the Docker container

markdown_to_confluence-0.3.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+md2conf/__init__.py,sha256=AtPkcrgEezF8jnJ14ALB3VdF6UAWPR9EPSYtoi6y5Nc,402
+md2conf/__main__.py,sha256=ypjV_5mE0smlIRBFrpikgzXq18as2hY43HJxMLpzGp4,7145
+md2conf/api.py,sha256=uwIR_wBSQqvZ9XZ2m2009Hf8B5w7T5PUXJ88BU8CJmA,19520
+md2conf/application.py,sha256=5K-nCPHJZfIahjubrLtXTwI-zsTiD140fdYXDnh3GSk,9161
+md2conf/converter.py,sha256=MoGbXqh5rE4qkdxxY8RHcnoZ5mz0aEuFz9nmUnt0WdM,36397
+md2conf/emoji.py,sha256=IZeguWqcboeOyJkGLTVONDMO4ZXfYXPgfkp56PTI-hE,1924
+md2conf/entities.dtd,sha256=M6NzqL5N7dPs_eUA_6sDsiSLzDaAacrx9LdttiufvYU,30215
+md2conf/matcher.py,sha256=FgMFPvGiOqGezCs8OyerfsVo-iIHFoI6LRMzdcjM5UY,3693
+md2conf/mermaid.py,sha256=Alzkv0BY-lju4ojtBdW2qtCLZ59MO9kaS2RpQO6Kyfk,2304
+md2conf/processor.py,sha256=G-MIh1jGq9jjgogHnlnRUSrNgiV6_xO6Fy7ct9alqgM,4769
+md2conf/properties.py,sha256=WaVVOYSck7drVQfcBJmBMa7Mb0KVOZl9UZHvLS1Du8U,1892
+md2conf/puppeteer-config.json,sha256=-dMTAN_7kNTGbDlfXzApl0KJpAWna9YKZdwMKbpOb60,159
+md2conf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_to_confluence-0.3.1.dist-info/LICENSE,sha256=Pv43so2bPfmKhmsrmXFyAvS7M30-1i1tzjz6-dfhyOo,1077
+markdown_to_confluence-0.3.1.dist-info/METADATA,sha256=pTnAvuTg_rgETAUZbsN_5HYbOwXE7qVpDGvhaXMwB2Y,14936
+markdown_to_confluence-0.3.1.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+markdown_to_confluence-0.3.1.dist-info/entry_points.txt,sha256=F1zxa1wtEObtbHS-qp46330WVFLHdMnV2wQ-ZorRmX0,50
+markdown_to_confluence-0.3.1.dist-info/top_level.txt,sha256=_FJfl_kHrHNidyjUOuS01ngu_jDsfc-ZjSocNRJnTzU,8
+markdown_to_confluence-0.3.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+markdown_to_confluence-0.3.1.dist-info/RECORD,,

{markdown_to_confluence-0.2.7.dist-info → markdown_to_confluence-0.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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.2.7"
+__version__ = "0.3.1"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2022-2024, Levente Hunyadi"
+__copyright__ = "Copyright 2022-2025, 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-2024, Levente Hunyadi
+Copyright 2022-2025, Levente Hunyadi
 
 :see: https://github.com/hunyadi/md2conf
 """
@@ -38,9 +38,12 @@ class Arguments(argparse.Namespace):
     ignore_invalid_url: bool
     heading_anchors: bool
     root_page: Optional[str]
+    keep_hierarchy: bool
     generated_by: Optional[str]
     render_mermaid: bool
     diagram_output_format: Literal["png", "svg"]
+    local: bool
+    headers: dict[str, str]
     webui_links: bool
 
 
@@ -107,6 +110,12 @@ def main() -> None:
         dest="root_page",
         help="Root Confluence page to create new pages. If omitted, will raise exception when creating new pages.",
     )
+    parser.add_argument(
+        "--keep-hierarchy",
+        action="store_true",
+        default=False,
+        help="Maintain source directory structure when exporting to Confluence.",
+    )
     parser.add_argument(
         "--generated-by",
         default="This page has been generated with a tool.",
@@ -169,14 +178,12 @@ def main() -> None:
         "--webui-links",
         action="store_true",
         default=False,
-        help="Enable Confluence Web UI links.",
+        help="Enable Confluence Web UI links. (Typically required for on-prem versions of Confluence.)",
     )
 
     args = Arguments()
     parser.parse_args(namespace=args)
 
-    # NOTE:  If we switch to modern type aware CLI tool like typer
-    #  the following line won't be necessary
     args.mdpath = Path(args.mdpath)
 
     logging.basicConfig(
@@ -189,6 +196,7 @@ def main() -> None:
         ignore_invalid_url=args.ignore_invalid_url,
         generated_by=args.generated_by,
         root_page_id=args.root_page,
+        keep_hierarchy=args.keep_hierarchy,
         render_mermaid=args.render_mermaid,
         diagram_output_format=args.diagram_output_format,
         webui_links=args.webui_links,