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:
1 parent
24f9740d97
commit
eaf202ec83
1 file changed
+14
-11
@@ -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
|
||||
|
||||
Reference in new issue
Block a user