Document recent behavior changes in README (AI)

Found while reviewing README completeness against the last bug-fix
pass:
- "Crawl health" bullet didn't mention the new rootFailed case (the
  root author-listing fetch failing outright, distinct from every
  individual author's listing failing).
- "Back link" feature bullet still described the old fixed-to-page-1
  behavior instead of the fixed return-to-referring-page behavior.
- No mention that #list-view/#article-view are checked for at startup
  with a friendly error, unlike the truly-optional mount points.
- No mention that author directory names are case-sensitive and
  matched exactly against #author/... URLs and profile lookups.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AXSVPS3UmmASiiprPfcnUd
This commit is contained in:
biosiasandClaude Sonnet 5 committed 2026-09-12 16:27:17 +02:00
1 parent 24f9740d97
commit eaf202ec83
1 file changed
+14 -11
+14 -11
View File
@@ -25,7 +25,7 @@ A minimal CMS where articles are Markdown files rendered in the browser. No buil
- **Client-side search** — the search box in the header filters all articles by title, description, author, category, and tags in-memory. Navigates to `#search/query` so results are bookmarkable; results paginate the same way the article list does.
- **Reading time** — estimated from the article word count (200 wpm) and shown on list cards and in article headers. Computed automatically; no frontmatter field needed.
- **Table of contents** — auto-generated from `h2`/`h3` headings and inserted at the top of the article body. Only appears when the article has three or more headings.
- **Back link** — a "← Back to articles" link above every article for one-click navigation back to the list.
- **Back link** — a "← Back to articles" link above every article, returning to whatever list, filter, or search page (and page number) the reader actually came from rather than always resetting to page 1 of everything.
- **Pagination** — article list paginates at 20 articles per page; page state is encoded in the hash so browser history works.
- **Author, category, and tag filtering** — clicking an author name, category badge, or tag pill shows a filtered list. All three support pagination.
- **Responsive layout** — layout, cards, images, and pagination all adapt to narrow screens (breakpoint at 640 px).
@@ -130,10 +130,12 @@ Steps:
To change an article's date, tags, or draft status later, rename its file — its content doesn't
need to change. `author` is derived from the containing directory — no frontmatter field needed
for it either. Because every one of these is encoded in the file name, discovering an article's
metadata never requires fetching anything beyond the directory listing that already reveals it —
no further per-article request at all, which is what makes the "Article discovery & caching"
section below possible.
for it either. Treat the directory name as case-sensitive and exact: it's matched exactly (not
case-insensitively) against `#author/...` URLs and author-profile lookups, so avoid two author
directories that differ only in case. Because every one of these is encoded in the file name,
discovering an article's metadata never requires fetching anything beyond the directory listing
that already reveals it — no further per-article request at all, which is what makes the "Article
discovery & caching" section below possible.
> **A note on trust:** article and author-bio Markdown is rendered directly via marked.js with no
> HTML-sanitization pass — anyone who can write a `.md` file here can include raw HTML, including
@@ -280,7 +282,7 @@ The site-level CSS files (`reset.css`, `header.css`, `layout.css`) are optional
<div id="article-view" hidden></div>
```
Place these wherever you want the CMS to appear. The router toggles `hidden` between them on navigation. A search box and tag/year filter lists are optional and can go anywhere else in the page — see "Search, article list, and tag list as independent pieces" below.
Place these wherever you want the CMS to appear. The router toggles `hidden` between them on navigation. A search box and tag/year filter lists are optional and can go anywhere else in the page — see "Search, article list, and tag list as independent pieces" below. Unlike those, `#list-view`/`#article-view` are both required — router.js checks for them at startup and shows a clear error (scoped to whichever of the two is present, or the whole page if neither is) instead of silently failing if one is missing.
### 3. Script — before `</body>`
@@ -485,11 +487,12 @@ of content is ever fetched per page view.
a large site to a handful of requests instead of hydrating the entire article set up front. The
page count is exact once the whole set's been scanned, and a lower bound (at least one more
page) until then.
- **Crawl health** — if every author's directory listing fails outright, or very few of the
known candidate files parsed successfully (a malformed file name, or a total breakage like the
wrong origin or CORS misconfigured), a small warning banner is shown above the article list
instead of silently rendering an empty page (see `getCrawlStats()` /
`renderCrawlHealthWarning()` in `js/discovery.js` / `js/views.js`).
- **Crawl health** — if the root author-listing fetch fails outright, if every individual
author's own directory listing fails, or if very few of the known candidate files parsed
successfully (a malformed file name, or a total breakage like the wrong origin or CORS
misconfigured), a small warning banner is shown above the article list instead of silently
rendering an empty page (see `getCrawlStats()` / `renderCrawlHealthWarning()` in
`js/discovery.js` / `js/views.js`).
- **Design rationale** — the original crawler design (wave-based crawling with a per-article
listing fetch, recency prioritisation, HTML-autoindex fallback, long-term "deploy and forget"
constraints) is documented in