Commit 804ad77 h

Pat Ambrosio · 26-08-26 19:31

An index page is its directory, and cannot clobber the blog index

Changes: 2 files +96 -3

Changes (Side-by-Side)

Raw

commit 804ad77cbb5ebc69681c1505948310591c7f74ff
Author: Pat Ambrosio <cp.ambrosio@gmail.com>
Date:   Wed Aug 26 19:31:18 2026 +0800

    An index page is its directory, and cannot clobber the blog index
    
    "index" is a filesystem convention, not part of the address: the page is
    reached at its directory's URL. Left in the trail the last crumb read
    "index" -- a filename presented to the reader as a place -- so a trailing
    "index" segment is dropped and the directory becomes the current crumb.
    
    Only a trailing one, and only beneath at least one directory: a page named
    "indexing" keeps its own crumb, and a page at the top of pages/ would have
    nothing left to name.
    
    That exposed a second bug in the same walk. Intermediate segments always
    pointed at the site root, on the reasoning that jenny renders no index for
    a directory -- true until a directory could have an index.md. A section
    that does have a landing page now links to it, so the trail through the
    thesis reaches the thesis instead of sending the reader home.
    
    And a third, older and worse: pages/index.md lands on the blog's own
    index, which is written earlier in the build, so the page silently
    replaced the post list with itself and the front page stopped being an
    index at all. It is refused now, with a message naming the file and
    saying what to do -- refused rather than resolved, because either file
    could reasonably be what the author meant and guessing makes one of them
    vanish without saying so.
    
    Verified by resolving every breadcrumb link on every page of the site: 55
    links, none broken.
    
    Tests: the dropped segment, the directory as current crumb, a sibling
    linking back to it, a directory without an index still pointing home, a
    page whose name merely starts with "index", and the refused collision
    leaving the post list intact. Checked by mutation -- restoring the index
    crumb, sending sections home again, allowing the collision -- each caught.
    
    Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
    Claude-Session: https://claude.ai/code/session_01WnSAstgnDYdKPwLGv1YZE5

diff --git a/share/jenny/lib/components.sh b/share/jenny/lib/components.sh
index 7f56967..8d822e3 100644
--- a/share/jenny/lib/components.sh
+++ b/share/jenny/lib/components.sh
@@ -272,6 +272,19 @@ render_pages () {
     esac
 
     out="$dist/${rel%.md}.html"
+
+    # pages/index.md would land on the blog's own index, which is written
+    # earlier in the build -- so the page silently replaced the post list with
+    # itself and the front page stopped being an index at all. Refused rather
+    # than resolved: either file could reasonably be what the author meant,
+    # and guessing would make one of them vanish without saying so.
+    if [ "${rel%.md}" = "index" ]; then
+      echo "$T ! Skipping $pages_dir/$rel: it would overwrite the blog index." >&2
+      echo "$T   Name it something else, or put it in a subdirectory." >&2
+      BUILD_FAILED=1
+      continue
+    fi
+
     outdir=$(dirname "$out")
     mkdir -p "$outdir"
 
@@ -426,16 +439,33 @@ render_page () {
   done
   segs+=("$walk")
 
+  # "index" is a filesystem convention, not part of the address: the page is
+  # reached at its directory's URL, so the directory is what the trail should
+  # name. Left in, the last crumb read "index" -- a filename presented to the
+  # reader as a place.
+  # Only a trailing "index" beneath at least one directory. At the top level
+  # there would be nothing left to name, and the page is the site root, which
+  # the site title already links to.
+  if [ "${#segs[@]}" -gt 1 ] && [ "${segs[$(( ${#segs[@]} - 1 ))]}" = "index" ]; then
+    unset 'segs[$(( ${#segs[@]} - 1 ))]'
+    segs=("${segs[@]}")
+  fi
+
   local i=0 n=${#segs[@]}
   for seg in "${segs[@]}"; do
     i=$((i + 1))
     acc="${acc:+$acc/}$seg"
     if [ "$i" -eq "$n" ]; then
       up="$prefix/$acc"
+    elif [ -f "$PAGES_DIR/$acc/index.md" ]; then
+      # An intermediate segment with an index.md is a real page, reached at
+      # its directory. Before pages could be indexes every intermediate
+      # segment pointed at the site root, so a trail through a section that
+      # does have a landing page sent the reader home instead.
+      up="$prefix/$acc/"
     else
-      # An intermediate segment is a directory, which jenny does not render
-      # an index for. It still names the section, so it points at the site
-      # root rather than a page that does not exist.
+      # A directory jenny renders no index for. It still names the section,
+      # so it points at the site root rather than a page that does not exist.
       up="$prefix/"
     fi
     crumbs="${crumbs}${up}$(printf '\t')$(printf '%s' "$seg" | tr '-' ' ')
diff --git a/test/regressions.sh b/test/regressions.sh
index ac5362d..e18a687 100755
--- a/test/regressions.sh
+++ b/test/regressions.sh
@@ -1083,6 +1083,69 @@ assert_file_contains "$al/.dist/index.html" 'padding-right: 1.5em;'
 it "the build is clean"
 assert_eq "$stderr_output" ""
 
+suite "an index page is its directory"
+
+# "index" is a filesystem convention, not part of the address: the page is
+# reached at its directory's URL. Left in the trail, the last crumb read
+# "index" -- a filename presented to the reader as a place.
+
+ix="$TMPROOT/indexpage"
+make_blog_min "$ix" 1 10
+mkdir -p "$ix/pages/thesis/mdd" "$ix/pages/notes/method"
+printf '# The Thesis\n\nBody.\n' > "$ix/pages/thesis/mdd/index.md"
+printf '# Artifacts\n\nBody.\n' > "$ix/pages/thesis/mdd/artifacts.md"
+printf '# Intro\n\nBody.\n' > "$ix/pages/notes/method/intro.md"
+run_jenny_split "$ix"
+
+it "the page renders at its directory"
+assert_file_exists "$ix/.dist/thesis/mdd/index.html"
+
+it "the trail does not name the file"
+ix_head=$("$GREP" -o '<header>.*</header>' "$ix/.dist/thesis/mdd/index.html" | head -1)
+assert_not_contains "$ix_head" '>index<'
+
+it "the directory is the current crumb instead"
+assert_contains "$ix_head" 'class="current">mdd</a>'
+
+it "a sibling links back to the directory, not the site root"
+# Intermediate segments used to point home because no directory had a page.
+# One with an index.md does, and sending the reader home from a section that
+# has a landing page is worse than not linking at all.
+sib_head=$("$GREP" -o '<header>.*</header>' "$ix/.dist/thesis/mdd/artifacts.html" | head -1)
+assert_contains "$sib_head" 'href="../../thesis/mdd/">mdd</a>'
+
+it "a directory with no index still points home"
+# Nothing to link to there, so the old behaviour is right and stays.
+no_ix=$("$GREP" -o '<header>.*</header>' "$ix/.dist/notes/method/intro.html" | head -1)
+assert_contains "$no_ix" 'href="../../">method</a>'
+
+it "a page whose name merely starts with index keeps its crumb"
+# The rule fires on a segment named exactly "index"; "indexing" is a page like
+# any other and must keep its own trail.
+mkdir -p "$ix/pages/solo"
+printf '# Indexing\n\nBody.\n' > "$ix/pages/solo/indexing.md"
+run_jenny_split "$ix"
+idx_like=$("$GREP" -o '<header>.*</header>' "$ix/.dist/solo/indexing.html" | head -1)
+assert_contains "$idx_like" 'class="current">indexing</a>'
+
+it "a page at the top of pages/ cannot overwrite the blog index"
+# pages/index.md lands on the blog's own index, which is written earlier in the
+# build -- so the page silently replaced the post list with itself and the
+# front page stopped being an index. Refused rather than resolved: either file
+# could be what the author meant, and guessing makes one vanish without saying
+# so.
+printf '# Root\n\nBody.\n' > "$ix/pages/index.md"
+run_jenny_split "$ix"
+assert_contains "$stderr_output" 'would overwrite the blog index'
+assert_file_contains "$ix/.dist/index.html" 'class="post-link"'
+# Removed and rebuilt so the clean-build check below is not reading the
+# warning this test provoked on purpose.
+rm "$ix/pages/index.md"
+run_jenny_split "$ix"
+
+it "the build is clean"
+assert_eq "$stderr_output" ""
+
 suite "headings are addressable"
 
 # A document long enough to link within needs its headings to be targets. Any