refactor: separate navigation title resolution

Signed-off-by: squidfunk <martin.donath@squidfunk.com>

python/tests/integration/test_config.py

@@ -134,9 +134,7 @@ def test_navigation_title_precedes_metadata_and_heading(tmp_path: Path) -> None:
     config = _make_yml_project(
         tmp_path,
         yml_extra=(
-            "  custom_dir: overrides\n"
-            "nav:\n"
-            "  - Configured title: index.md"
+            "  custom_dir: overrides\nnav:\n  - Configured title: index.md"
         ),
     )
     (tmp_path / "docs" / "index.md").write_text(
@@ -151,6 +149,56 @@ def test_navigation_title_precedes_metadata_and_heading(tmp_path: Path) -> None:
     assert (tmp_path / "site" / "index.html").read_text() == "Configured title"
 
 
+@pytest.mark.parametrize(
+    ("navigation", "expected"),
+    [
+        ("  - index.md\n  - Later: index.md", "Hello"),
+        ("  - First: index.md\n  - Second: index.md", "First"),
+    ],
+)
+def test_first_navigation_occurrence_owns_page_title(
+    tmp_path: Path, navigation: str, expected: str
+) -> None:
+    """Duplicate pages retain the title assigned by their first occurrence."""
+    config = _make_yml_project(
+        tmp_path,
+        yml_extra=(f"  custom_dir: overrides\nnav:\n{navigation}"),
+    )
+    custom = _make_custom_dir(tmp_path)
+    (custom / "main.html").write_text("{{ page.title }}", encoding="utf-8")
+
+    _build(config)
+
+    assert (tmp_path / "site" / "index.html").read_text() == expected
+
+
+def test_only_root_index_page_becomes_navigation_homepage(
+    tmp_path: Path,
+) -> None:
+    """Nested index paths and similarly named links are never the homepage."""
+    config = _make_yml_project(
+        tmp_path,
+        yml_extra=(
+            "  custom_dir: overrides\n"
+            "nav:\n"
+            "  - Guide: guide/index.md\n"
+            "  - Website: https://example.com/index.md"
+        ),
+    )
+    guide = tmp_path / "docs" / "guide"
+    guide.mkdir()
+    (guide / "index.md").write_text("# Guide\n", encoding="utf-8")
+    custom = _make_custom_dir(tmp_path)
+    (custom / "main.html").write_text(
+        "{{ nav.homepage.title if nav.homepage else 'none' }}",
+        encoding="utf-8",
+    )
+
+    _build(config)
+
+    assert (tmp_path / "site" / "index.html").read_text() == "Hello"
+
+
 # ---------------------------------------------------------------------------
 # Theme loading: both zensical.toml and mkdocs.yml
 # ---------------------------------------------------------------------------

python/tests/integration/test_literate_nav.py

@@ -140,6 +140,40 @@ plugins:
     ]
 
 
+def test_explicit_page_title_precedes_metadata_and_heading(
+    tmp_path: Path,
+) -> None:
+    """Literate navigation supplies the same page-title precedence as MkDocs."""
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    overrides = tmp_path / "overrides"
+    overrides.mkdir()
+    (overrides / "main.html").write_text("{{ page.title }}", encoding="utf-8")
+    (docs / "index.md").write_text(
+        "---\ntitle: Metadata title\n---\n\n# Heading title\n",
+        encoding="utf-8",
+    )
+    (docs / "SUMMARY.md").write_text(
+        "* [Configured title](index.md)\n", encoding="utf-8"
+    )
+    config = tmp_path / "mkdocs.yml"
+    config.write_text(
+        """\
+site_name: Literate navigation
+theme:
+  name: material
+  custom_dir: overrides
+plugins:
+  - literate-nav
+""",
+        encoding="utf-8",
+    )
+
+    zensical.build(str(config), _BUILD_OPTIONS)
+
+    assert (tmp_path / "site" / "index.html").read_text() == "Configured title"
+
+
 def test_resolves_configured_directory_through_nested_literate_nav(
     tmp_path: Path,
 ) -> None:

python/tests/integration/test_tags.py

@@ -145,6 +145,30 @@ def test_builds_listings_references_toc_and_search_without_export(
     assert not (tmp_path / "site" / "tags.json").exists()
 
 
+def test_navigation_titles_flow_through_listings_and_search(
+    tmp_path: Path,
+) -> None:
+    """Title-sensitive plugin outputs consume finalized page titles."""
+    config = _write_project(tmp_path)
+    with config.open("a", encoding="utf-8") as file:
+        file.write(
+            "nav:\n"
+            "  - Catalog: index.md\n"
+            "  - Configured Rust: guide/rust.md\n"
+            "  - Python: guide/python.md\n"
+        )
+
+    zensical.build(str(config), _BUILD_OPTIONS)
+
+    listing = (tmp_path / "site" / "index.html").read_text()
+    search = json.loads((tmp_path / "site" / "search.json").read_text())
+    assert "Configured Rust" in listing
+    assert "Rust page" not in listing
+    assert any(
+        item["path"][-1] == "Configured Rust" for item in search["items"]
+    )
+
+
 def test_inherits_tags_from_meta_file(tmp_path: Path) -> None:
     """Tags supplied by Material meta participate in page tag mappings."""
     _write_project(tmp_path)