cook-ssg 2.3.0 → 2.4.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
@@ -134,6 +134,7 @@ The build process performs the following steps, in this order:
134
134
  1. **Creates `/dist`** - Removes existing dist folder and recreates it
135
135
  2. **Copies `/src` to `/dist`** - All source files are copied (excludes `.md` files and `buildOnlyPaths`)
136
136
  3. **Processes Markdown** - Converts `.md` files to `.html` with front matter support; groups pages into `collections.*` by directory
137
+ * With `collections: { html: true }`, HTML pages that start with YAML front matter join the same collections
137
138
  4. **Generates image derivatives** - Responsive AVIF/WebP variants at configured widths, with a cross-build disk cache (`images` config)
138
139
  5. **Runs custom-user `before` plugins** - Runs once before file processing
139
140
  6. **Converts pages to directories** - `about.html` becomes `about/index.html` for extensionless URLs
@@ -207,6 +208,10 @@ export default {
207
208
  // absolute URLs you set yourself (sitemap.url, data.siteUrl).
208
209
  basePath: '',
209
210
 
211
+ // HTML pages that start with YAML front matter join collections.<folder>
212
+ // like markdown files (default: false)
213
+ collections: { html: false },
214
+
210
215
  // Sitemap: set url to enable (default: '' = no sitemap.xml)
211
216
  sitemap: {
212
217
  url: 'https://www.yoursite.com',
@@ -417,6 +422,7 @@ Generate repeated elements from arrays or collections. Perfect for blog listings
417
422
  **Data Sources:**
418
423
  - `collections.blog` - From markdown files in `/src/blog/`
419
424
  - `collections.docs` - From markdown files in `/src/docs/`
425
+ - HTML pages with front matter in those folders too, when `collections: { html: true }` is set
420
426
  - `items` - From `/config/data.js`
421
427
  - Any array in your data configuration
422
428
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cook-ssg",
3
- "version": "2.3.0",
3
+ "version": "2.4.0",
4
4
  "description": "Cook your static pages into a beautifully performing site. Static site generation the web platform way.",
5
5
  "type": "module",
6
6
  "bin": {
package/scripts/build.js CHANGED
@@ -22,6 +22,7 @@ import fingerprintAssets from './plugins/fingerprint-assets.js';
22
22
  import generateFormats from './plugins/generate-formats.js';
23
23
  import generateFragments from './plugins/generate-fragments.js';
24
24
  import generateSitemap from './plugins/generate-sitemap-xml.js';
25
+ import htmlCollections from './plugins/html-collections.js';
25
26
  import minifySrc from './plugins/minify-src.js';
26
27
  import { optimizeImagesGenerate, optimizeImagesRewrite } from './plugins/optimize-images.js';
27
28
  import processMarkdown from './plugins/process-markdown.js';
@@ -90,6 +91,11 @@ class Build {
90
91
  // PLUGIN: Process markdown files (.md -> .html)
91
92
  await processMarkdown({store, data});
92
93
 
94
+ // PLUGIN: HTML pages with front matter join collections (opt-in:
95
+ // `collections: { html: true }`). Pre-loop so data-repeat and the feed
96
+ // see every page; merges with markdown collections.
97
+ await htmlCollections({store, data});
98
+
93
99
  // PLUGIN: Generate responsive image derivatives (AVIF/WebP at multiple widths)
94
100
  await optimizeImagesGenerate({store});
95
101
 
@@ -0,0 +1,211 @@
1
+ /**
2
+ * @file html-collections.js
3
+ * @description HTML pages with YAML front matter join collections, the way
4
+ * markdown files do. Opt-in: `collections: { html: true }`.
5
+ *
6
+ * Runs before the file loop (right after markdown) so `data-repeat`,
7
+ * the Atom feed and the JSON formats see every page:
8
+ *
9
+ * src/posts/hello.html ---
10
+ * title: Hello
11
+ * date: 2026-11-01
12
+ * ---
13
+ * <p>...</p>
14
+ *
15
+ * → collections.posts = [{ title: 'Hello', url: '/posts/hello/', slug: 'hello', date: '2026-11-01', ... }]
16
+ *
17
+ * Rules (match markdown collections and the built output):
18
+ * - collection = first folder under the served root (srcPath, or
19
+ * srcPath/<siteRoot>); files at the root or outside it join none
20
+ * - only files that start with `---` front matter; `draft: true` is skipped
21
+ * - buildOnlyPaths folders and excludePaths (tested on the dist path) skipped
22
+ * - URL follows convertPageToDirectory (posts/a.html → /posts/a/)
23
+ * - newest date first, undated last; merged with markdown collections
24
+ */
25
+
26
+ // IMPORTS
27
+ // -----------------------------
28
+ import chalk from 'chalk';
29
+ import { promises as fs } from 'node:fs';
30
+ import { existsSync } from 'node:fs';
31
+ import path from 'node:path';
32
+ import matter from 'gray-matter';
33
+ import Logger from '../utils/logger/logger.js';
34
+ import Util from '../utils/util/util.js';
35
+ import { addToCollection, sortCollections, toCollectionItem } from '../utils/collections/collections.js';
36
+ import { normalizeSiteRoot } from '../utils/site-root/site-root.js';
37
+
38
+ // Config
39
+ import {
40
+ buildOnlyPaths as buildOnlyPathsConfig,
41
+ collections as collectionsConfig,
42
+ convertPageToDirectory,
43
+ distPath as distPathConfig,
44
+ excludePaths as excludePathsConfig,
45
+ siteRoot as siteRootConfig,
46
+ srcPath as srcPathConfig,
47
+ } from '../utils/config/config.js';
48
+
49
+
50
+ // ============================================================================
51
+ // Pure helpers (exported for unit testing)
52
+ // ============================================================================
53
+
54
+ /**
55
+ * Path of a file relative to the served root, or null when outside it.
56
+ * @param {string} relPath - Relative to srcPath, e.g. 'pages/posts/a.html'
57
+ * @param {string} [siteRoot]
58
+ * @returns {string|null} e.g. 'posts/a.html'
59
+ */
60
+ function servedRelPath(relPath, siteRoot) {
61
+ const root = normalizeSiteRoot(siteRoot);
62
+ if (!root) return relPath;
63
+ return relPath.startsWith(`${root}/`) ? relPath.slice(root.length + 1) : null;
64
+ }
65
+
66
+ /**
67
+ * Collection name for an HTML page: its first folder under the served root.
68
+ * @param {string} relPath - Relative to srcPath, e.g. 'posts/a.html'
69
+ * @param {string} [siteRoot]
70
+ * @returns {string|null}
71
+ */
72
+ export function htmlCollectionName(relPath, siteRoot) {
73
+ const served = servedRelPath(relPath, siteRoot);
74
+ if (!served) return null;
75
+ const parts = served.split('/');
76
+ return parts.length > 1 ? parts[0] : null;
77
+ }
78
+
79
+ /**
80
+ * Visitor URL of an HTML page once built.
81
+ * @param {string} relPath - Relative to srcPath
82
+ * @param {Object} opts
83
+ * @param {string} [opts.siteRoot]
84
+ * @param {boolean} [opts.convertDisabled] - convertPageToDirectory.disabled
85
+ * @param {boolean} [opts.convertExcluded] - Page matches convertPageToDirectory.excludePaths
86
+ * @returns {string|null}
87
+ */
88
+ export function htmlPageUrl(relPath, { siteRoot, convertDisabled, convertExcluded } = {}) {
89
+ const served = servedRelPath(relPath, siteRoot);
90
+ if (served === null) return null;
91
+ let url = `/${served}`;
92
+ if (/(^|\/)index\.html$/.test(served)) return url.replace(/index\.html$/, '');
93
+ if (convertDisabled || convertExcluded) return url;
94
+ return url.replace(/\.html$/, '/');
95
+ }
96
+
97
+ /**
98
+ * Collection page data for an HTML page (same shape as markdown pages).
99
+ * @param {string} relPath - Relative to srcPath
100
+ * @param {Object} frontMatter - Parsed YAML
101
+ * @param {Object} opts - Same as htmlPageUrl
102
+ * @returns {Object}
103
+ */
104
+ export function htmlPageData(relPath, frontMatter, opts = {}) {
105
+ const base = path.basename(relPath, '.html');
106
+ const slug = base === 'index' ? path.basename(path.dirname(relPath)) : base;
107
+ const rawDate = frontMatter.date;
108
+ const parsed = rawDate ? new Date(rawDate) : null;
109
+ const valid = parsed && !isNaN(parsed);
110
+ return {
111
+ ...frontMatter,
112
+ title: frontMatter.title || Util.convertToCapSpaces(slug, 'kebab'),
113
+ url: htmlPageUrl(relPath, opts),
114
+ slug,
115
+ collection: htmlCollectionName(relPath, opts.siteRoot),
116
+ date: templateDate(rawDate),
117
+ // Parsed Date is only for sorting
118
+ _dateSort: valid ? parsed : null,
119
+ };
120
+ }
121
+
122
+ /**
123
+ * Date string for templates, on the calendar day the author wrote.
124
+ * - YAML dates (gray-matter gives a UTC-midnight Date) → YYYY-MM-DD
125
+ * - Strings starting YYYY-MM-DD keep that day; converting through UTC
126
+ * would move "2026-11-01T23:30:00-05:00" to 2026-11-02
127
+ * - Any other string is kept as written, like markdown pages
128
+ * @param {Date|string|undefined} rawDate
129
+ * @returns {string|null}
130
+ */
131
+ function templateDate(rawDate) {
132
+ if (!rawDate) return null;
133
+ if (rawDate instanceof Date) return isNaN(rawDate) ? null : rawDate.toISOString().split('T')[0];
134
+ const str = String(rawDate);
135
+ const ymd = str.match(/^\d{4}-\d{2}-\d{2}/);
136
+ return ymd ? ymd[0] : str;
137
+ }
138
+
139
+
140
+ // ============================================================================
141
+ // Plugin
142
+ // ============================================================================
143
+
144
+ /**
145
+ * @param {Object} opts
146
+ * @param {Object} opts.store - Build store; collections are merged into store.collections
147
+ * @param {Object} opts.data - User data; data.collections is set
148
+ * @param {string} [opts.srcPath] - Overrides config (tests, custom pipelines)
149
+ * @param {string} [opts.distPath]
150
+ * @param {string} [opts.siteRoot]
151
+ * @param {boolean} [opts.enabled] - Defaults to config `collections.html`
152
+ * @param {string[]} [opts.buildOnlyPaths]
153
+ * @param {Array<RegExp|string>} [opts.excludePaths]
154
+ */
155
+ export default async function htmlCollections({
156
+ store,
157
+ data,
158
+ srcPath = srcPathConfig,
159
+ distPath = distPathConfig,
160
+ siteRoot = siteRootConfig,
161
+ enabled = collectionsConfig && collectionsConfig.html,
162
+ buildOnlyPaths = buildOnlyPathsConfig || [],
163
+ excludePaths = excludePathsConfig || [],
164
+ }) {
165
+ if (!enabled || !existsSync(srcPath)) return;
166
+
167
+ const excludes = excludePaths.map(p => (p instanceof RegExp ? p : new RegExp(p)));
168
+ const convertExcludes = (convertPageToDirectory && convertPageToDirectory.excludePaths) || [];
169
+ const convertDisabled = !!(convertPageToDirectory && convertPageToDirectory.disabled);
170
+
171
+ const files = (Util.getPaths(srcPath, srcPath, []) || []).filter(f => f.endsWith('.html'));
172
+ if (!store.collections) store.collections = {};
173
+
174
+ let collected = 0;
175
+ for (const file of files) {
176
+ const relPath = path.relative(srcPath, file).split(path.sep).join('/');
177
+ if (buildOnlyPaths.some(dir => relPath === dir || relPath.startsWith(`${dir}/`))) continue;
178
+
179
+ const distFile = `${distPath}/${relPath}`;
180
+ if (excludes.some(r => r.test(distFile))) continue;
181
+
182
+ const collection = htmlCollectionName(relPath, siteRoot);
183
+ if (!collection) continue;
184
+
185
+ const src = await fs.readFile(file, 'utf-8');
186
+ if (!src.startsWith('---')) continue;
187
+
188
+ let frontMatter;
189
+ try {
190
+ ({ data: frontMatter } = matter(src));
191
+ } catch (err) {
192
+ console.warn(chalk.yellow(`\n[html-collections] ${relPath}: invalid front matter (skipped from collections)`));
193
+ console.warn(` ${err && err.message ? err.message : err}`);
194
+ continue;
195
+ }
196
+ if (!frontMatter || !Object.keys(frontMatter).length || frontMatter.draft === true) continue;
197
+
198
+ const convertExcluded = convertExcludes.some(str => distFile.includes(str));
199
+ const page = htmlPageData(relPath, frontMatter, { siteRoot, convertDisabled, convertExcluded });
200
+ addToCollection(store.collections, collection, toCollectionItem(page));
201
+ collected += 1;
202
+ }
203
+
204
+ sortCollections(store.collections);
205
+ data.collections = store.collections;
206
+
207
+ if (collected) {
208
+ Logger.persist.header('\nHTML Collections');
209
+ Logger.persist.success(`Collected ${collected} HTML page(s)`);
210
+ }
211
+ }
@@ -16,6 +16,7 @@ import Util from '../utils/util/util.js';
16
16
  import { renderTemplate } from '../utils/interpolate/interpolate.js';
17
17
 
18
18
  // Config
19
+ import { addToCollection, sortCollections, toCollectionItem } from '../utils/collections/collections.js';
19
20
  import { distPath, srcPath, markdown as markdownConfig } from '../utils/config/config.js';
20
21
 
21
22
 
@@ -323,37 +324,13 @@ ${pageData.content}
323
324
 
324
325
  for (const page of this.processedFiles) {
325
326
  if (page.collection) {
326
- // Initialize collection array if needed
327
- if (!this.store.collections[page.collection]) {
328
- this.store.collections[page.collection] = [];
329
- }
330
-
331
327
  // Add page to collection (without full content to save memory)
332
- this.store.collections[page.collection].push({
333
- title: page.title,
334
- url: page.url,
335
- slug: page.slug,
336
- date: page.date,
337
- description: page.description,
338
- // Include any other front matter fields except content
339
- ...Object.fromEntries(
340
- Object.entries(page).filter(([key]) =>
341
- !['content', 'sourcePath', 'outputPath', 'collection'].includes(key)
342
- )
343
- ),
344
- });
328
+ addToCollection(this.store.collections, page.collection, toCollectionItem(page));
345
329
  }
346
330
  }
347
331
 
348
332
  // Sort collections by date (newest first)
349
- for (const collectionName of Object.keys(this.store.collections)) {
350
- this.store.collections[collectionName].sort((a, b) => {
351
- if (!a._dateSort && !b._dateSort) return 0;
352
- if (!a._dateSort) return 1;
353
- if (!b._dateSort) return -1;
354
- return b._dateSort - a._dateSort;
355
- });
356
- }
333
+ sortCollections(this.store.collections);
357
334
  }
358
335
 
359
336
  // EXPORT WRAPPER
@@ -0,0 +1,54 @@
1
+ /**
2
+ * @file collections.js
3
+ * @description Shared helpers for building collections (markdown and HTML
4
+ * pages grouped by folder, exposed as `collections.<name>` in templates).
5
+ */
6
+
7
+ /** Page keys used only during the build, never exposed to templates. */
8
+ const BUILD_ONLY_KEYS = ['content', 'sourcePath', 'outputPath', 'collection'];
9
+
10
+ /**
11
+ * Shape a page into a collection item: title/url/slug/date/description
12
+ * first, then every other front matter field, minus build-only keys
13
+ * (`content` is dropped to save memory).
14
+ * @param {Object} page
15
+ * @returns {Object}
16
+ */
17
+ export function toCollectionItem(page) {
18
+ return {
19
+ title: page.title,
20
+ url: page.url,
21
+ slug: page.slug,
22
+ date: page.date,
23
+ description: page.description,
24
+ ...Object.fromEntries(Object.entries(page).filter(([key]) => !BUILD_ONLY_KEYS.includes(key))),
25
+ };
26
+ }
27
+
28
+ /**
29
+ * Append an item to a named collection, creating it if needed.
30
+ * @param {Object<string, Object[]>} collections
31
+ * @param {string} name
32
+ * @param {Object} item
33
+ */
34
+ export function addToCollection(collections, name, item) {
35
+ if (!collections[name]) collections[name] = [];
36
+ collections[name].push(item);
37
+ }
38
+
39
+ /**
40
+ * Sort every collection in place: newest `_dateSort` first, undated items
41
+ * last, original order kept for ties (Array#sort is stable).
42
+ * @param {Object<string, Object[]>} collections
43
+ */
44
+ export function sortCollections(collections) {
45
+ for (const items of Object.values(collections)) {
46
+ if (!Array.isArray(items)) continue;
47
+ items.sort((a, b) => {
48
+ if (!a._dateSort && !b._dateSort) return 0;
49
+ if (!a._dateSort) return 1;
50
+ if (!b._dateSort) return -1;
51
+ return b._dateSort - a._dateSort;
52
+ });
53
+ }
54
+ }
@@ -104,6 +104,11 @@ const defaultConfig = {
104
104
  // Markdown: Convert .md files to HTML with front matter support
105
105
  // Markdown files in /src are converted to HTML in /dist
106
106
  // Front matter (YAML between ---) becomes template variables
107
+ // Collections from HTML pages: pages that start with YAML front matter
108
+ // join `collections.<first folder>` like markdown files do (opt-in).
109
+ collections: {
110
+ html: false,
111
+ },
107
112
  markdown: {
108
113
  // Default layout template to wrap content (null = basic HTML wrapper)
109
114
  layout: null,
@@ -308,6 +313,7 @@ export const {
308
313
  basePath,
309
314
  buildOnlyPaths,
310
315
  bundle,
316
+ collections,
311
317
  components,
312
318
  convertPageToDirectory,
313
319
  distPath,