ai-release-notes 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -160,17 +160,91 @@ The main parts are simple:
160
160
  See [Instructions](#instructions).
161
161
  - `output` lists the Markdown and/or HTML release files to create. Use
162
162
  `{env}`, `{lang}`, `{from}`, and `{to}` in their names. Missing `--from` and
163
- `--to` become `start` and `end`.
163
+ `--to` become `start` and `end`. A name carrying `{from}` or `{to}` belongs
164
+ to a single release, so regenerating it rewrites that file. A name without
165
+ either is shared by every release, and each new one is added to it.
164
166
  - `outputIndex` is optional. It maintains a release summary with links to
165
167
  every release file. It may be one destination or a list, for example one
166
168
  Markdown and one HTML summary. Add `{lang}` when each language needs its own
167
- summary. Index templates can place links between those summaries with
168
- `{{languages}}` (or `{{langages}}`). The switcher merges languages from the
169
- current prompt with localized index files already present on disk.
169
+ summary. `entryTemplate` sets the shape of one listed release; see
170
+ [Index entries](#index-entries). Index templates can place links between those
171
+ summaries with `{{languages}}` (or `{{langages}}`). That slot is spent the
172
+ first time an index is written: afterwards the switcher is found by the markup
173
+ it was rendered as, so a generated page carries a switcher rather than a
174
+ marker of ours. A single language shows no switcher at all. The switcher
175
+ merges languages from the current prompt with localized index files already
176
+ present on disk. An index template is assumed to be written in the first
177
+ `prompt.languages` entry, and an index in any other language is translated.
170
178
 
171
179
  Custom instruction and summary templates are optional. The generated config
172
180
  keeps their lines commented until you need them.
173
181
 
182
+ ### Index entries
183
+
184
+ One listed release is one template: markup with `{{slot}}` placeholders, and
185
+ nothing else. The bundled one lives in
186
+ `templates/default-release-summary-entry.md` and `.html`:
187
+
188
+ ```html
189
+ <section class="release-entry">
190
+ <h2>Release {{toVersion}}</h2>
191
+ <p><em>{{environment}} · {{date}} · Changes since {{fromVersion}}</em></p>
192
+ <p><a href="{{href}}">Read release notes</a></p>
193
+ </section>
194
+ ```
195
+
196
+ The slots are `{{environment}}`, `{{date}}`, `{{fromVersion}}`, `{{toVersion}}`
197
+ and `{{href}}`. Everything else is yours to write. Point `entryTemplate` at your
198
+ own file to replace it:
199
+
200
+ ```yaml
201
+ outputIndex:
202
+ - format: html
203
+ saveTo: ./releases/{env}/{lang}/index.html
204
+ template: ./templates/summary.html
205
+ entryTemplate: ./templates/entry.html
206
+ ```
207
+
208
+ The entry template is read from its file on every run and translated together
209
+ with the summary template, so an index never carries a copy of it: editing the
210
+ file is what changes the shape.
211
+
212
+ Each entry stores what the index knows about its release — environment,
213
+ versions, date, link — in a comment marker, and the whole list is rendered again
214
+ on every run. Edit the entry template, or switch the index to another language,
215
+ and the entire history is relabelled at the next release. The list is bounded by
216
+ `<!-- ai-release-notes:releases -->` and `<!-- ai-release-notes:/releases -->`;
217
+ everything outside those two lines belongs to the summary template.
218
+
219
+ An entry that carries no record is kept word for word, below the rendered ones,
220
+ since there is nothing to render it from.
221
+
222
+ ### The release page
223
+
224
+ An HTML release note is rendered inside `templates/default-release-note.html`,
225
+ and that file owns every word of the page: its `<title>`, its footer, and its
226
+ styles are the template's own. `--template` (or `output[].template`) points at a
227
+ file of yours instead. These slots are filled, and anything else is left as
228
+ written:
229
+
230
+ | Slot | Value |
231
+ |------|-------|
232
+ | `{{content}}` | The release note itself |
233
+ | `{{projectName}}` | `projectName` from the config |
234
+ | `{{fromVersion}}` / `{{toVersion}}` | The version range |
235
+ | `{{environment}}` | `--env` |
236
+ | `{{date}}` | The resolved release date |
237
+ | `{{version}}` | The `ai-release-notes` version |
238
+
239
+ A page title is a sentence, so it is written in the template's `<title>` rather
240
+ than assembled from the versions: there is no `{{title}}` slot.
241
+
242
+ ### The first release
243
+
244
+ `--from start` — the default — reads the whole history, so there is no previous
245
+ version to compare against. The release note says `First release` where a
246
+ comparison would go, and the file name still uses `start` for `{from}`.
247
+
174
248
  For the exact configuration and comments, see the annotated
175
249
  [example `.ai-release-notes.yml`](examples/.ai-release-notes.yml). The
176
250
  [examples guide](examples/README.md) then walks through a first run, writing
@@ -284,6 +358,13 @@ console.log(result.markdown);
284
358
  console.log(result.html);
285
359
  ```
286
360
 
361
+ `markdownToHtml(markdown, options?)` wraps Markdown in the bundled release-note
362
+ template, which supplies the page title and footer:
363
+
364
+ ```typescript
365
+ markdownToHtml(markdown, { trustedHtml: true });
366
+ ```
367
+
287
368
  ---
288
369
 
289
370
  ## CI/CD Integration