From a0f1ed67d9e35523cb12641ccf3315aaf334fa34 Mon Sep 17 00:00:00 2001
From: biosias <jakub@gdos.sk>
Date: Sat, 12 Sep 2026 16:00:20 +0200
Subject: [PATCH] Document embedding search, article list, and tag list
 independently (AI)

New README subsection under "Embedding in an existing page" explaining
that #list-view/#article-view (the only required pair, also where
search results render), #search-form/#search-input, #tag-filters, and
#year-filters are all independent mount points that can be placed
anywhere in a custom layout rather than stacked the way the demo does
-- includes a #year-filters example, which wasn't documented anywhere
before despite still being fully supported by renderFilterNavigation().

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AXSVPS3UmmASiiprPfcnUd
---
 README.md | 50 +++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 41 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7583cd0..4543dd5 100644
--- a/README.md
+++ b/README.md
@@ -276,15 +276,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.
-
-Optionally add a search form anywhere in the page:
-
-```html
-<form id="search-form" role="search">
-    <input type="search" id="search-input" placeholder="Search articles…" autocomplete="off">
-</form>
-```
+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.
 
 ### 3. Script — before `</body>`
 
@@ -301,6 +293,46 @@ Optionally add a search form anywhere in the page:
 > ```
 > All internal fetches (articles, templates, marked.js) resolve relative to the module files via `import.meta.url` and work automatically — only the HTML tags need a path pointing at the right place.
 
+### Search, article list, and tag list as independent pieces
+
+The mount points above don't have to sit next to each other, or even all be present — each is a
+plain element the router looks up by `id`, wherever it happens to be in your page. This lets you
+scatter search, the article list, and the tag list across a custom layout (search box in the site
+header, tag list in a sidebar, articles in the main column) instead of stacking them the way the
+demo does.
+
+- **Article list + single article — `#list-view` / `#article-view`.** These two are the only
+  required pair; the router toggles `hidden` between them and always needs both present somewhere
+  on the page. This pair is also where **search results** render — there's no separate results
+  container, so any page using the search box below still needs `#list-view` on it somewhere to
+  actually show what was searched for.
+- **Search box — `#search-form` / `#search-input`.** Fully optional and independent; place it
+  anywhere (e.g. a site-wide header, not necessarily near the list). Submitting it navigates to
+  `#search/query`; matches render into `#list-view`.
+  ```html
+  <form id="search-form" role="search">
+      <input type="search" id="search-input" placeholder="Search articles…" autocomplete="off">
+  </form>
+  ```
+- **Tag list — `#tag-filters`.** Optional; put a container (a `<nav>` works well) anywhere, e.g. a
+  sidebar. It's automatically filled in with one link per tag in use (alphabetical, with an
+  article count) every time a list view renders — no manual updates needed. Clicking a tag
+  navigates to `#tag/tag-id`, rendering the filtered list into `#list-view`.
+  ```html
+  <nav id="tag-filters" aria-label="Filter by tag"></nav>
+  ```
+- **Year list — `#year-filters`** (optional, not used by this repo's own demo but supported the
+  same way): a container that gets filled in with one link per year 2026 down to 2009 that has at
+  least one article, linking to `#category/year-YYYY`. Can appear alongside `#tag-filters` or on
+  its own.
+  ```html
+  <nav id="year-filters" aria-label="Filter by year"></nav>
+  ```
+
+Both filter lists are populated by the same function on every list render, so whichever of
+`#tag-filters`/`#year-filters` is present just gets filled in — omit either one (or both) and
+nothing breaks, the article list and search still work standalone.
+
 ### Minimal example
 
 ```html