feat(document): add parent title prefix via .pages file

[geopanther]

Summary

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 → "Folder1 overview" and "Folder2 overview").

Adapted from iamjackg/md2cf#127 by @jeffmercerVG.

Changes

• Parse add-parent-title-as-prefix from .pages YAML files
• Prefix child page titles with parent folder title when enabled
• Type-safe guards for None values on both parent and page titles

Tests

• New test: test_get_pages_from_directory_with_pages_file_multi_level_conflicting_titles
• All 23 document tests pass

[geopanther]

Maintainer Review

Verdict: ✅ Approve with suggestions

Addresses a real Confluence constraint — all pages in a space must have unique titles. The .pages file approach is opt-in and per-folder, which is the right design.

Good:

• Uses existing .pages infrastructure — no new CLI flags needed
• Type-safe null guards for both parent_page_title and processed_page.title
• Clean test covering the exact use case from the PR description

Suggestions (non-blocking):

• The upstream PR uses a simple string check. We improved it to .get() which is more Pythonic and handles missing keys + falsy values in one call
• Consider documenting this in README alongside the existing .pages file docs
• Future enhancement: could also support a custom separator (default space) via prefix-separator: " - "

Compared to upstream: Our adaptation is cleaner — the original PR had a formatting-only change to __repr__ mixed in. We omitted that correctly.