Listings

Start & End

listing-start and listing-end bracket the list: rendered once each, before the first item and after the last, but only when the list is not empty. Both are optional:

<!-- localhoster:listing collection="blog" -->
  <!-- localhoster:listing-start
       ```
       <ul class="posts">
       ``` -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
  <!-- localhoster:listing-end
       ```
       </ul>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="blog" -->

Empty

listing-empty (optional) is rendered instead of the whole list when nothing matches, so a filtered listing shows a friendly placeholder rather than blank space:

<!-- localhoster:listing collection="blog" -->
  <!-- localhoster:listing-filter field="status" op="eq" value="published" -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
  <!-- localhoster:listing-empty
       ```
       <p class="muted">No posts yet.</p>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="blog" -->

Items

listing-item (required) is the markup rendered once per record:

<!-- localhoster:listing collection="blog" -->
  <!-- localhoster:listing-item
       ```
       <article class="card">
         <h3><a href="{{url}}">{{title}}</a></h3>
         <p class="muted">{{date}} · {{tags}}</p>
         {{summary}}
       </article>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="blog" -->

Separators

listing-separator (optional) is inserted between items, never before the first or after the last. A listing uses either a separator or a heading, not both:

<!-- localhoster:listing collection="blog" -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
  <!-- localhoster:listing-separator
       ```
       <hr>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="blog" -->

Headings

listing-heading (optional) is rendered per item but shown only when it changes from the item before it, so a sorted list subdivides into headed groups; put any rule or spacing into the heading markup itself:

<!-- localhoster:listing collection="posts" -->
  <!-- localhoster:listing-sort field="category" -->
  <!-- localhoster:listing-heading
       ```
       <h3>{{category}}</h3>
       ``` -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="posts" -->

Filtering

listing-filter keeps records where field compares to value by op. Repeating it requires all of the conditions; for any-of (OR) instead, group filters in a filter-any (below):

<!-- localhoster:listing collection="guides" -->
  <!-- localhoster:listing-filter field="topic" op="contains" value="caddy" -->
  <!-- localhoster:listing-filter field="date" op="gte" value="2026-01-01" -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="guides" -->

Filter Any

listing-filter-any is a paired block holding two or more plain listing-filters; a record passes if it matches any of them (OR). It sits anywhere in the pipeline, like a filter, and may contain only listing-filter commands:

<!-- localhoster:listing collection="posts" -->
  <!-- localhoster:listing-filter-any -->
    <!-- localhoster:listing-filter field="category" op="eq" value="news" -->
    <!-- localhoster:listing-filter field="category" op="eq" value="updates" -->
  <!-- localhoster:/listing-filter-any -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a> ({{category}})</li>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="posts" -->

Sorting

listing-sort orders the set by a field:

<!-- localhoster:listing collection="blog" -->
  <!-- localhoster:listing-sort field="date" order="desc" -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="blog" -->

Grouping

listing-group groups records by by, sorts each group by using/order, then takes a slice with start and count (default 0 and 1, so one representative per group). Raise count for the top N from each group, or set start to pick a position, like the second; a group may yield fewer:

<!-- localhoster:listing collection="posts" -->
  <!-- localhoster:listing-group by="category" using="date" order="desc" count="3" -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a> ({{category}})</li>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="posts" -->

Limiting

listing-limit takes a slice with start and count. It can sit anywhere in the pipeline, so you can trim before or after a group, or page through results:

<!-- localhoster:listing collection="blog" -->
  <!-- localhoster:listing-sort field="date" order="desc" -->
  <!-- localhoster:listing-limit start="0" count="5" -->
  <!-- localhoster:listing-item
       ```
       <li><a href="{{url}}">{{title}}</a></li>
       ``` -->
   … localhoster writes the generated list here …
<!-- localhoster:/listing collection="blog" -->

Errors

A listing is validated before its list is generated; a problem is reported against the page and the listing, and the site is left unchanged until it is fixed (other sites still run):

Next steps