From fa212fe273fd1ba34a623fded536ca93fceb01bb Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 11:32:12 -0700 Subject: [PATCH 1/3] add template return type selection guide --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 008f8fb..c317995 100644 --- a/README.md +++ b/README.md @@ -875,6 +875,19 @@ This is just a file with access to global vars: ${testVar}`, export default templateIterator ``` +### Choosing a template return type + +Use the simplest return type that fits your needs: + +| Return type | Multiple outputs | Custom filename | Use when | +|---|---|---|---| +| String | No | No (derived from template filename) | Single file, filename from template name | +| Object | No | Yes | Single file with a custom output path | +| Array | Yes | Yes | Fixed set of output files known at build time | +| AsyncIterator | Yes | Yes | Any async work, or a dynamic number of outputs | + +Start with a string return and only switch to a more complex type when you need what it provides. An async generator is the right choice when you need to do async work (such as calling `renderInnerPage` on multiple pages) and produce more than one output file. + ### RSS Feed Template Example Templates receive the standard variables available to pages, so its possible to perform page introspection and generate RSS feeds of website content. From 2c5481f5865e2bd57d5cdadecd23a5b693290ee7 Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 12:03:06 -0700 Subject: [PATCH 2/3] Clarify AsyncIterator use case in template return type guide The previous description implied AsyncIterator was needed for any async work, which is wrong -- all template forms support async functions. The distinguishing characteristic is streaming/dynamic number of outputs. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c317995..0b5ae26 100644 --- a/README.md +++ b/README.md @@ -884,9 +884,9 @@ Use the simplest return type that fits your needs: | String | No | No (derived from template filename) | Single file, filename from template name | | Object | No | Yes | Single file with a custom output path | | Array | Yes | Yes | Fixed set of output files known at build time | -| AsyncIterator | Yes | Yes | Any async work, or a dynamic number of outputs | +| AsyncIterator | Yes | Yes | Dynamic or unknown number of outputs at build time | -Start with a string return and only switch to a more complex type when you need what it provides. An async generator is the right choice when you need to do async work (such as calling `renderInnerPage` on multiple pages) and produce more than one output file. +Start with a string return and only switch to a more complex type when you need what it provides. All template forms can do async work (string, object, and array all support `async` functions). Choose AsyncIterator specifically when the number of output files is not known until the template runs, or when you want to stream outputs one at a time rather than building the full list in memory first. ### RSS Feed Template Example From 2ab00aa8365342cfbdd6d866b60842eb665563e7 Mon Sep 17 00:00:00 2001 From: Bret Comnes Date: Sat, 18 Apr 2026 12:53:28 -0700 Subject: [PATCH 3/3] Use 'Custom output path' in template return type table header --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0b5ae26..86e7345 100644 --- a/README.md +++ b/README.md @@ -879,9 +879,9 @@ export default templateIterator Use the simplest return type that fits your needs: -| Return type | Multiple outputs | Custom filename | Use when | +| Return type | Multiple outputs | Custom output path | Use when | |---|---|---|---| -| String | No | No (derived from template filename) | Single file, filename from template name | +| String | No | No (derived from template filename) | Single file, output path derived from template filename | | Object | No | Yes | Single file with a custom output path | | Array | Yes | Yes | Fixed set of output files known at build time | | AsyncIterator | Yes | Yes | Dynamic or unknown number of outputs at build time |