Named fragment templates for page_list item rendering #36

New issue

Open

opened 2026-06-03 10:16:06 +02:00 by Carsten · 0 comments

Carsten commented

2026-06-03 10:16:06 +02:00

Owner

Summary

Currently page_list renders each item with a hardcoded layout: link, optional date, optional summary. There is no way to change the per-item output without modifying the directive source. This proposal adds support for named fragment templates — small .mu files that define how each list item is rendered.

Motivation

Different uses of page_list need different layouts:

A blog archive wants: title link + date + summary
An author index wants: title link only (no summary)
A book list might want: title link + year + language

Today this requires separate directives or boolean suppression flags (show_summary=false) that accumulate over time. A template system handles all variations with no new directive arguments.

Proposed interface

```md
::page_list section=authors display_field=sort_name item_template=author-item limit=0::
```

If item_template is omitted, current behaviour is preserved (backward compatible).

Template resolution

Fragment templates live in system/templates/fragments/page_list/. The directive looks for <item_template>.mu in that directory. If not found, falls back to the built-in default.

Template context

Each item template is rendered once per matched page, with the following context keys available:

Key	Value
`title`	Value of `display_field` (or `title` as fallback)
`route`	Page route for link construction
`summary`	`summary` frontmatter value
`date`	`date` frontmatter value
`slug`	Page slug
`<field>`	Any other frontmatter field, by name

The link itself (styled_theme_link(title, route)) is pre-rendered by the directive and passed as a link context key, since template files cannot call Python functions directly.

Default built-in template (matches current output exactly):

```

{link}
{date}
{summary}
```

Implementation sketch

In directive_page_list, check for item_template arg (added to _RESERVED)
If present, resolve system/templates/fragments/page_list/<name>.mu via context["root_dir"]
Read the template, substitute context keys using a simple str.format_map() or the existing template rendering path
Append rendered item to output; fall back to built-in layout if template file missing

Relationship to other directives

The same fragment template pattern could be extended to other directives (downloads, comments) in follow-up PRs, making it a general CMS convention rather than a one-off feature.

**Summary** Currently `page_list` renders each item with a hardcoded layout: link, optional date, optional summary. There is no way to change the per-item output without modifying the directive source. This proposal adds support for **named fragment templates** — small `.mu` files that define how each list item is rendered. **Motivation** Different uses of `page_list` need different layouts: - A blog archive wants: title link + date + summary - An author index wants: title link only (no summary) - A book list might want: title link + year + language Today this requires separate directives or boolean suppression flags (`show_summary=false`) that accumulate over time. A template system handles all variations with no new directive arguments. **Proposed interface** \`\`\`md ::page_list section=authors display_field=sort_name item_template=author-item limit=0:: \`\`\` If `item_template` is omitted, current behaviour is preserved (backward compatible). **Template resolution** Fragment templates live in `system/templates/fragments/page_list/`. The directive looks for `<item_template>.mu` in that directory. If not found, falls back to the built-in default. **Template context** Each item template is rendered once per matched page, with the following context keys available: | Key | Value | |-----|-------| | `title` | Value of `display_field` (or `title` as fallback) | | `route` | Page route for link construction | | `summary` | `summary` frontmatter value | | `date` | `date` frontmatter value | | `slug` | Page slug | | `<field>` | Any other frontmatter field, by name | The link itself (`styled_theme_link(title, route)`) is pre-rendered by the directive and passed as a `link` context key, since template files cannot call Python functions directly. **Default built-in template** (matches current output exactly): \`\`\` - {link} {date} {summary} \`\`\` **Implementation sketch** 1. In `directive_page_list`, check for `item_template` arg (added to `_RESERVED`) 2. If present, resolve `system/templates/fragments/page_list/<name>.mu` via `context["root_dir"]` 3. Read the template, substitute context keys using a simple `str.format_map()` or the existing template rendering path 4. Append rendered item to output; fall back to built-in layout if template file missing **Relationship to other directives** The same fragment template pattern could be extended to other directives (`downloads`, `comments`) in follow-up PRs, making it a general CMS convention rather than a one-off feature.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Carsten/NomadNet_CMS_Starter#36

No description provided.

Rows
Columns