fix: placeholder index.md should be removed after (not during) running "ap dev"

Author: softwareentrepreneer

src/afterpython/builders/index_md.py

@@ -4,17 +4,12 @@
 from afterpython.const import CONTENT_TYPES, PLACEHOLDER_INDEX_MARKER
 
 
-def _legacy_placeholder_content(content_type: str) -> str:
-    return f"""---
-title: ← {content_type.capitalize()}
----
-
-This is a placeholder index page. The actual {content_type} landing page is rendered by SvelteKit.
-"""
-
-
-def _legacy_welcome_content(content_type: str) -> str:
-    return f"""# Welcome to AfterPython
+def _placeholder_content(content_type: str) -> str:
+    """Current placeholder body. Marker is an HTML comment so it embeds invisibly;
+    _is_afterpython_placeholder_index keys off it to tell our files apart from
+    user-authored ones."""
+    return f"""{PLACEHOLDER_INDEX_MARKER}
+# Welcome to AfterPython
 
 Welcome to your project's {content_type}! This is a starter page to help you get started.
 
@@ -35,6 +30,19 @@ def _legacy_welcome_content(content_type: str) -> str:
 """
 
 
+def _legacy_placeholder_content(content_type: str) -> str:
+    """Frozen fingerprint of the arrow-stub placeholder written between commits
+    49f30c1 and 3a560e2 (no marker). Kept solely so projects built in that window
+    are still recognized as ours and cleaned up rather than blocking with the
+    'reserved' error. Do not edit — that would break recognition."""
+    return f"""---
+title: ← {content_type.capitalize()}
+---
+
+This is a placeholder index page. The actual {content_type} landing page is rendered by SvelteKit.
+"""
+
+
 def _is_afterpython_placeholder_index(index_md, content_type: str) -> bool:
     """Return True only for non-doc index.md files generated by AfterPython."""
     content = index_md.read_text(encoding="utf-8", errors="ignore")
@@ -43,7 +51,6 @@ def _is_afterpython_placeholder_index(index_md, content_type: str) -> bool:
     return (
         PLACEHOLDER_INDEX_MARKER in content
         or normalized_content == _legacy_placeholder_content(content_type).strip()
-        or normalized_content == _legacy_welcome_content(content_type).strip()
     )
 
 
@@ -76,25 +83,15 @@ def create_placeholder_index_md_files():
             )
             continue
 
-        content_path = ap.paths.afterpython_path / content_type
-        myst_yml_path = content_path / "myst.yml"
-
-        # Prepend index.md to TOC in myst.yml
-        if myst_yml_path.exists():
-            # Create placeholder index.md file
-            _write_index_file(content_type)
-            myst_data = read_yaml(myst_yml_path) or {}
-            toc = myst_data.get("project", {}).get("toc", [])
+        _write_index_file(content_type)
 
-            # Check if index.md is already first in TOC
-            if not toc or toc[0].get("file") != "index.md":
-                # Prepend index.md to TOC in myst.yml
-                new_toc = [{"file": "index.md"}, *toc]
-                if "project" not in myst_data:
-                    myst_data["project"] = {}
-                myst_data["project"]["toc"] = new_toc
-                write_yaml(myst_yml_path, myst_data)
-                click.echo(f"Added index.md to TOC in {myst_yml_path}")
+        # Prepend index.md to TOC in myst.yml (skip if already first).
+        myst_data = read_yaml(myst_yml_path) or {}
+        toc = myst_data.get("project", {}).get("toc", [])
+        if not toc or toc[0].get("file") != "index.md":
+            myst_data.setdefault("project", {})["toc"] = [{"file": "index.md"}, *toc]
+            write_yaml(myst_yml_path, myst_data)
+            click.echo(f"Added index.md to TOC in {myst_yml_path}")
 
 
 def delete_placeholder_index_md_files():

src/afterpython/cli/commands/build.py

@@ -171,7 +171,13 @@ def _move_files(
             print(f"Moved: {source} to {destination}")
 
     build_content_json()
-    delete_placeholder_index_md_files()
+    # In dev mode the MyST `start` server is watching these files. Deleting
+    # them here would make MyST re-index without the placeholder and revert
+    # to using the first content file as the section index — exactly what
+    # the placeholder was created to prevent. `ap dev` cleans them up in
+    # its `finally` block after MyST has been shut down.
+    if not dev_build:
+        delete_placeholder_index_md_files()
 
     website_static = ap.paths.website_path / "static"
     website_static.mkdir(parents=True, exist_ok=True)

src/afterpython/cli/commands/dev.py

@@ -11,6 +11,7 @@
 import click
 from click.exceptions import Exit
 
+from afterpython.builders import delete_placeholder_index_md_files
 from afterpython.cli.commands.build import postbuild, prebuild
 from afterpython.const import CONTENT_TYPES
 from afterpython.utils import find_available_port, find_node_env
@@ -218,3 +219,6 @@ def cleanup_processes():
         pass
     finally:
         cleanup_processes()
+        # Now that MyST watchers are gone, clean up the placeholders
+        # postbuild() intentionally left behind for dev mode.
+        delete_placeholder_index_md_files()

src/afterpython/tools/myst.py

@@ -143,14 +143,11 @@ def _write_index_file(content_type: tContentType):
             f"and update the reference in afterpython/{content_type}/myst.yml."
         )
 
-    index_content = f"""---
-title: ← {content_type.capitalize()}
----
+    # Lazy import to avoid the circular dep with builders/index_md.py, which
+    # already lazy-imports _write_index_file from this module.
+    from afterpython.builders.index_md import _placeholder_content
 
-{PLACEHOLDER_INDEX_MARKER}
-
-This is a placeholder index page. The actual {content_type} landing page is rendered by SvelteKit.
-"""
+    index_content = _placeholder_content(content_type)
     index_file.write_text(index_content)
     return index_file