feat(document): add --title-from-filename flag

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:

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

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",
+    )