fix: reserve and only remove placeholder index.md

Author: softwareentrepreneer

.github/workflows/ci.yml

@@ -124,7 +124,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@v0.9.5
+        uses: prefix-dev/setup-pixi@v0.9.6
         with:
           pixi-version: v0.67.2
           cache: true

pixi.lock

@@ -71,8 +71,8 @@ build-backend = "uv_build"
 module-name = "afterpython"
 module-root = "src"
 
-[tool.uv.sources]
-afterpython = { path = ".", editable = true }
+# [tool.uv.sources]
+# afterpython = { path = ".", editable = true }
 
 [tool.pyright]
 typeCheckingMode = "basic"

pyproject.toml

@@ -1,7 +1,50 @@
 import click
 
 import afterpython as ap
-from afterpython.const import CONTENT_TYPES
+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
+
+Welcome to your project's {content_type}! This is a starter page to help you get started.
+
+## Getting Started
+
+Replace this placeholder content with your own. Here's what you can do:
+
+- Creating new `.md` or `.ipynb` files in the `afterpython/{content_type}/` directory
+- Writing in MyST Markdown format
+- Adding images to the `afterpython/static/` directory and referencing them
+
+## Resources
+
+- [AfterPython's Project Website](https://afterpython.afterpython.org)
+- [MyST Markdown Guide](https://mystmd.org)
+
+Start building your amazing project! 🚀
+"""
+
+
+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")
+    normalized_content = content.strip()
+
+    return (
+        PLACEHOLDER_INDEX_MARKER in content
+        or normalized_content == _legacy_placeholder_content(content_type).strip()
+        or normalized_content == _legacy_welcome_content(content_type).strip()
+    )
 
 
 def create_placeholder_index_md_files():
@@ -71,10 +114,23 @@ def delete_placeholder_index_md_files():
         myst_yml_path = content_path / "myst.yml"
         index_md = content_path / "index.md"
 
-        # Delete index.md from source
+        # Delete index.md from source only when it is an AfterPython-generated placeholder.
         if index_md.exists():
+            if not _is_afterpython_placeholder_index(index_md, content_type):
+                raise click.ClickException(
+                    f"Found existing 'afterpython/{content_type}/index.md'.\n"
+                    f"\n"
+                    f"'afterpython/{content_type}/index.md' is reserved for internal use by AfterPython.\n"
+                    f"The '/{content_type}' route is owned by the SvelteKit listing page,\n"
+                    f"so user-authored non-doc index.md files are not supported.\n"
+                    f"\n"
+                    f"Please rename this file to something else "
+                    f"(e.g., '{content_type}_intro.md') and update the reference in "
+                    f"afterpython/{content_type}/myst.yml."
+                )
+
             index_md.unlink()
-            click.echo(f"Deleted: {index_md}")
+            click.echo(f"Deleted placeholder: {index_md}")
 
         # Delete index.html from build output
         index_html = content_path / "_build" / "html" / "index.html"

src/afterpython/builders/index_md.py

@@ -2,3 +2,4 @@
 
 NODEENV_VERSION = "24.11.0"
 CONTENT_TYPES: set[tContentType] = {"doc", "blog", "tutorial", "example", "guide"}
+PLACEHOLDER_INDEX_MARKER = "<!-- afterpython:placeholder-index -->"

src/afterpython/const.py

@@ -124,7 +124,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@v0.9.5
+        uses: prefix-dev/setup-pixi@v0.9.6
         with:
           pixi-version: v0.67.2
           cache: true

src/afterpython/templates/ci-workflow-template.yml

@@ -9,8 +9,11 @@
 
 import subprocess
 
+import click
+
 import afterpython as ap
 from afterpython._io.yaml import read_yaml, write_yaml
+from afterpython.const import PLACEHOLDER_INDEX_MARKER
 from afterpython.utils import deep_merge
 
 
@@ -113,7 +116,7 @@ def _write_index_file(content_type: tContentType):
     Note: This only creates the file. TOC modification is handled by the build process.
 
     Raises:
-        FileExistsError: If index.md already exists (users shouldn't create this file).
+        click.ClickException: If a non-placeholder index.md already exists.
     """
     if content_type == "doc":
         return  # Doc doesn't need a placeholder index.md
@@ -123,22 +126,29 @@ def _write_index_file(content_type: tContentType):
 
     # Check if user created an index.md file
     if index_file.exists():
-        raise FileExistsError(
+        existing_content = index_file.read_text(encoding="utf-8", errors="ignore")
+        if PLACEHOLDER_INDEX_MARKER in existing_content:
+            return index_file
+
+        raise click.ClickException(
             f"\n"
-            f"Found existing 'index.md' in afterpython/{content_type}/\n"
+            f"Found existing 'afterpython/{content_type}/index.md'\n"
             f"\n"
-            f"The 'index.md' file is reserved for internal use by AfterPython.\n"
+            f"'afterpython/{content_type}/index.md' is reserved for internal use by AfterPython.\n"
             f"MyST treats the first file in TOC as index, which would conflict with\n"
-            f"SvelteKit (project-website-template)'s landing page route (/{content_type}).\n"
+            f"the SvelteKit listing page route '/{content_type}', which is owned by\n"
+            f"AfterPython's project website.\n"
             f"\n"
             f"Please rename your file to something else (e.g., '{content_type}_intro.md')\n"
-            f"and update the reference in afterpython/{content_type}/myst.yml"
+            f"and update the reference in afterpython/{content_type}/myst.yml."
         )
 
     index_content = f"""---
 title: ← {content_type.capitalize()}
 ---
 
+{PLACEHOLDER_INDEX_MARKER}
+
 This is a placeholder index page. The actual {content_type} landing page is rendered by SvelteKit.
 """
     index_file.write_text(index_content)