From a00d7675b3fd4e5bb4934b0d3b1b1f0b1e2807c1 Mon Sep 17 00:00:00 2001
From: geopanther <geopanther@mail.de>
Date: Wed, 13 May 2026 16:39:48 +0200
Subject: [PATCH] feat(document): add --title-from-filename flag

Add option to always use the filename as the page title, overriding
any title found in the document header or front matter. Useful when
multiple files share the same top-level heading but need distinct
Confluence page titles.

Mutually exclusive with --title. Errors when used with stdin input.

Adapted from iamjackg/md2cf#115 by @devzeb.
---
 mdfluence/__main__.py                    | 17 ++++++++-
 mdfluence/document.py                    |  5 ++-
 test_package/unit/test_document_title.py | 48 ++++++++++++++++++++++++
 3 files changed, 68 insertions(+), 2 deletions(-)
 create mode 100644 test_package/unit/test_document_title.py

diff --git a/mdfluence/__main__.py b/mdfluence/__main__.py
index 3c41cc5..952267f 100644
--- a/mdfluence/__main__.py
+++ b/mdfluence/__main__.py
@@ -98,11 +98,17 @@ def get_parser():
         help="upload the page tree starting from the top level (no top level parent)",
     )
 
-    page_group.add_argument(
+    title_group = page_group.add_mutually_exclusive_group()
+    title_group.add_argument(
         "-t",
         "--title",
         help="a title for the page. Determined from the document if missing",
     )
+    title_group.add_argument(
+        "--title-from-filename",
+        action="store_true",
+        help="always use the filename as the title of the page",
+    )
 
     page_group.add_argument(
         "-c",
@@ -719,6 +725,13 @@ def collect_pages_to_upload(args):
             )
             sys.exit(1)
 
+        if args.title_from_filename:
+            error_console.log(
+                "You cannot specify --title-from-filename "
+                "if uploading from standard input\n"
+            )
+            sys.exit(1)
+
         if args.title:
             pages_to_upload[0].title = args.title
     else:
@@ -741,6 +754,7 @@ def collect_pages_to_upload(args):
                     render_diagrams=args.render_diagrams,
                     mmdc_path=args.mmdc_path,
                     plantuml_path=args.plantuml_path,
+                    page_title_from_filename=args.title_from_filename,
                 )
             else:
                 try:
@@ -758,6 +772,7 @@ def collect_pages_to_upload(args):
                             render_diagrams=args.render_diagrams,
                             mmdc_path=args.mmdc_path,
                             plantuml_path=args.plantuml_path,
+                            page_title_from_filename=args.title_from_filename,
                         )
                     )
                 except FileNotFoundError:
diff --git a/mdfluence/document.py b/mdfluence/document.py
index 47ed981..4701d49 100644
--- a/mdfluence/document.py
+++ b/mdfluence/document.py
@@ -130,6 +130,7 @@ def get_pages_from_directory(
     render_diagrams: bool = False,
     mmdc_path: str | None = None,
     plantuml_path: str | None = None,
+    page_title_from_filename: bool = False,
 ) -> List[Page]:
     """
     Collect a list of markdown files recursively under the file_path directory.
@@ -249,6 +250,7 @@ def get_pages_from_directory(
                 render_diagrams=render_diagrams,
                 mmdc_path=mmdc_path,
                 plantuml_path=plantuml_path,
+                page_title_from_filename=page_title_from_filename,
             )
             processed_page.parent_title = parent_page_title
             processed_pages.append(processed_page)
@@ -272,6 +274,7 @@ def get_page_data_from_file_path(
     render_diagrams: bool = False,
     mmdc_path: str | None = None,
     plantuml_path: str | None = None,
+    page_title_from_filename: bool = False,
 ) -> Page:
     if not isinstance(file_path, Path):
         file_path = Path(file_path)
@@ -297,7 +300,7 @@ def get_page_data_from_file_path(
         plantuml_path=plantuml_path,
     )
 
-    if not page.title:
+    if page_title_from_filename or not page.title:
         page.title = file_path.stem
 
     page.file_path = file_path
diff --git a/test_package/unit/test_document_title.py b/test_package/unit/test_document_title.py
new file mode 100644
index 0000000..fb7bae7
--- /dev/null
+++ b/test_package/unit/test_document_title.py
@@ -0,0 +1,48 @@
+from pathlib import Path
+
+import mdfluence.document as doc
+from test_package.utils import FakePage
+
+
+def test_get_page_title_from_file(fs):
+    fs.create_file("/root-folder/some-page.md", contents="# Title from within file")
+
+    result = doc.get_page_data_from_file_path(
+        Path("/root-folder/some-page.md"), page_title_from_filename=False
+    )
+    assert result == FakePage(
+        title="Title from within file",
+    )
+
+
+def test_get_page_title_from_filename_if_no_title_in_file(fs):
+    fs.create_file("/root-folder/some-page.md")
+
+    result = doc.get_page_data_from_file_path(
+        Path("/root-folder/some-page.md"), page_title_from_filename=False
+    )
+    assert result == FakePage(
+        title="some-page",
+    )
+
+
+def test_get_page_title_from_filename_if_no_page_title_in_file(fs):
+    fs.create_file("/root-folder/some-page.md", contents="")
+
+    result = doc.get_page_data_from_file_path(
+        Path("/root-folder/some-page.md"), page_title_from_filename=True
+    )
+    assert result == FakePage(
+        title="some-page",
+    )
+
+
+def test_get_page_title_from_filename_if_page_title_in_file(fs):
+    fs.create_file("/root-folder/some-page.md", contents="# Title from within file")
+
+    result = doc.get_page_data_from_file_path(
+        Path("/root-folder/some-page.md"), page_title_from_filename=True
+    )
+    assert result == FakePage(
+        title="some-page",
+    )