From 930ebe2f2c3a8a00319182dacda930472ec3239c Mon Sep 17 00:00:00 2001
From: geopanther <geopanther@mail.de>
Date: Wed, 13 May 2026 16:47:45 +0200
Subject: [PATCH] feat(document): add parent title prefix via .pages file

Support `add-parent-title-as-prefix: true` in `.pages` YAML files to
prefix child page titles with the folder's title. Resolves title
collisions when multiple folders contain identically-named documents
(e.g., folder1/overview.md and folder2/overview.md).

Adapted from iamjackg/md2cf#127 by @jeffmercerVG.
---
 mdfluence/document.py              |  9 ++++++++
 test_package/unit/test_document.py | 33 ++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/mdfluence/document.py b/mdfluence/document.py
index 47ed981..7526366 100644
--- a/mdfluence/document.py
+++ b/mdfluence/document.py
@@ -218,12 +218,15 @@ def get_pages_from_directory(
                         .capitalize()
                     )
                 folder_title = parent_page_title
+        use_parent_title_as_prefix = False
         if use_pages_file and ".pages" in file_names:
             with open(current_path.joinpath(".pages")) as pages_fp:
                 pages_file_contents = yaml.safe_load(pages_fp)
             if "title" in pages_file_contents:
                 parent_page_title = pages_file_contents["title"]
                 folder_title = parent_page_title
+            if pages_file_contents.get("add-parent-title-as-prefix"):
+                use_parent_title_as_prefix = True
 
         folder_data[current_path]["title"] = folder_title
 
@@ -251,6 +254,12 @@ def get_pages_from_directory(
                 plantuml_path=plantuml_path,
             )
             processed_page.parent_title = parent_page_title
+            if (
+                use_parent_title_as_prefix
+                and parent_page_title
+                and processed_page.title
+            ):
+                processed_page.title = parent_page_title + " " + processed_page.title
             processed_pages.append(processed_page)
 
             # This replaces the title for the current folder with the title for the
diff --git a/test_package/unit/test_document.py b/test_package/unit/test_document.py
index 70e479b..1a50be5 100644
--- a/test_package/unit/test_document.py
+++ b/test_package/unit/test_document.py
@@ -227,6 +227,39 @@ def test_get_pages_from_directory_with_pages_file_multi_level(fs):
     ]
 
 
+def test_get_pages_from_directory_with_pages_file_multi_level_conflicting_titles(fs):
+    fs.create_file("/root-folder/sub-folder-a/some-page.md")
+    fs.create_file("/root-folder/sub-folder-b/some-page.md")
+    fs.create_file(
+        "/root-folder/sub-folder-a/.pages",
+        contents='title: "Folder A"\nadd-parent-title-as-prefix: true',
+    )
+    fs.create_file(
+        "/root-folder/sub-folder-b/.pages",
+        contents='title: "Folder B"\nadd-parent-title-as-prefix: true',
+    )
+
+    result = doc.get_pages_from_directory(Path("/root-folder"), use_pages_file=True)
+    assert result == [
+        FakePage(
+            title="Folder A",
+        ),
+        FakePage(
+            title="Folder A some-page",
+            file_path=Path("/root-folder/sub-folder-a/some-page.md"),
+            parent_title="Folder A",
+        ),
+        FakePage(
+            title="Folder B",
+        ),
+        FakePage(
+            title="Folder B some-page",
+            file_path=Path("/root-folder/sub-folder-b/some-page.md"),
+            parent_title="Folder B",
+        ),
+    ]
+
+
 def test_get_pages_from_directory_with_pages_file_single_level(fs):
     fs.create_file("/root-folder/some-page.md")
     fs.create_file("/root-folder/.pages", contents='title: "Root folder"')