fix: point nav at -__init__ page for packages with only private submodules (#44)

A package whose only submodules are private/internal is rendered as a leaf
in the navigation tree (its children aren't in generated_modules), but the
generator writes it as an "-__init__" page because those private submodules
exist on disk. Navigation then emitted the bare leaf path, producing a dead
link (e.g. prefect-cli-deploy in nav vs prefect-cli-deploy-__init__.mdx on
disk).

The leaf branch now points at whichever file was actually written: if the
plain page is absent but the -__init__ variant exists, use the latter. When
neither exists (e.g. pure unit tests with no files on disk) it falls back to
the plain name, preserving existing behavior.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zzstoatzz

src/mdxify/navigation.py

@@ -146,7 +146,18 @@ def tree_to_nav(tree: dict, parent_parts: list[str] | None = None, is_top_level:
                 # This is a leaf module with no submodules
                 module_name = info["_path"]
                 filename = module_name.replace(".", "-")
-                
+
+                # A module whose only submodules are private/internal is rendered
+                # as a leaf here (its public children aren't in the tree), but the
+                # generator still wrote it as an "-__init__" page because the
+                # private submodules exist on disk. Point navigation at whichever
+                # file was actually written so we don't emit a dead link.
+                if (
+                    not (output_dir / f"{filename}.mdx").exists()
+                    and (output_dir / f"{filename}-__init__.mdx").exists()
+                ):
+                    filename = f"{filename}-__init__"
+
                 if nav_prefix:
                     nav_path = str(nav_prefix / filename).replace("\\", "/")
                 else:

tests/test_navigation.py

@@ -495,4 +495,35 @@ def test_update_docs_json_with_tabs_structure(tmp_path):
     pages = python_sdk_anchor["pages"]
     assert len(pages) == 2
     assert "python-sdk/fastmcp-client" in pages
-    assert "python-sdk/fastmcp-server" in pages
+    assert "python-sdk/fastmcp-server" in pages
+
+def test_leaf_module_points_to_init_file_when_only_private_submodules(tmp_path):
+    """A package whose only submodules are private is written as an -__init__
+    page; navigation must point at that file, not the bare leaf name.
+
+    Regression test for dead links like prefect-cli-deploy (nav) vs
+    prefect-cli-deploy-__init__.mdx (file on disk).
+    """
+    # The public module list only contains the package itself; its submodules
+    # are all private and therefore not generated.
+    modules = ["mypackage.cli.deploy"]
+
+    # On disk, the generator wrote the page with an -__init__ suffix.
+    (tmp_path / "mypackage-cli-deploy-__init__.mdx").write_text("# deploy")
+
+    result = build_hierarchical_navigation(modules, tmp_path, skip_empty_parents=False)
+
+    flat = json.dumps(result)
+    assert "mypackage-cli-deploy-__init__" in flat
+    # And not the bare (nonexistent) leaf path.
+    assert '"mypackage-cli-deploy"' not in flat
+
+
+def test_leaf_module_keeps_plain_name_when_file_present(tmp_path):
+    """A normal leaf whose plain file exists keeps the plain nav path."""
+    modules = ["mypackage.tasks"]
+    (tmp_path / "mypackage-tasks.mdx").write_text("# tasks")
+
+    result = build_hierarchical_navigation(modules, tmp_path, skip_empty_parents=False)
+    assert "mypackage-tasks" in json.dumps(result)
+    assert "mypackage-tasks-__init__" not in json.dumps(result)