cook-ssg 2.0.0 → 2.1.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
@@ -440,6 +440,8 @@ export default {
440
440
 
441
441
  ---
442
442
 
443
+ Note: Project was started and used internally at PINT, Inc in 2020 and it was recently revived in 2025 and moved to use in 2026
444
+
443
445
  ## License
444
446
 
445
- MIT © 2020 Prof Thomas Powell
447
+ MIT © 2020 Thomas A. Powell
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cook-ssg",
3
- "version": "2.0.0",
3
+ "version": "2.1.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": {
@@ -52,11 +52,12 @@
52
52
  "url": "https://github.com/ProfPowell/cook/issues"
53
53
  },
54
54
  "dependencies": {
55
+ "@profpowell/code-block": "^2.7.0",
55
56
  "browser-sync": "^3.0.4",
56
57
  "chalk": "^5.4.1",
57
58
  "clean-css": "^5.3.3",
58
59
  "cli-cursor": "^5.0.0",
59
- "cli-spinners": "^3.3.0",
60
+ "cli-spinners": "^3.4.0",
60
61
  "fs-extra": "^11.3.2",
61
62
  "gray-matter": "^4.0.3",
62
63
  "html-minifier-terser": "^7.2.0",
@@ -66,10 +67,12 @@
66
67
  "marked": "^17.0.1",
67
68
  "rimraf": "^6.1.2",
68
69
  "sharp": "^0.34.5",
69
- "terser": "^5.44.1"
70
+ "terser": "^5.46.1"
70
71
  },
71
72
  "devDependencies": {
73
+ "happy-dom": "^20.8.9",
72
74
  "http-server": "^14.1.1",
75
+ "linkedom": "^0.18.12",
73
76
  "npm-check-updates": "^19.2.0"
74
77
  }
75
78
  }
package/scripts/build.js CHANGED
@@ -27,6 +27,7 @@ import repeatCollection from './plugins/repeat-collection.js';
27
27
  import replaceComponents from './plugins/replace-components.js';
28
28
  import applyTemplate from './plugins/apply-template.js';
29
29
  import escapeCodeBlocks from './plugins/escape-code-blocks.js';
30
+ import prerenderCodeBlocks from './plugins/prerender-code-blocks.js';
30
31
  import processHtmlFrontmatter from './plugins/process-html-frontmatter.js';
31
32
  import replaceInclude from './plugins/replace-include.js';
32
33
  import replaceInline from './plugins/replace-inline.js';
@@ -184,6 +185,10 @@ class Build {
184
185
  });
185
186
  }
186
187
 
188
+ // PLUGIN: Pre-render <code-block> with Declarative Shadow DOM
189
+ // Runs after restore — code-block content is decoded and ready for highlighting.
190
+ await prerenderCodeBlocks({file, allowType: ['.html']});
191
+
187
192
  // Write new, modified source back to the file
188
193
  await updatePage(file);
189
194
 
@@ -19,7 +19,7 @@ import path from 'node:path';
19
19
  import Util from '../utils/util/util.js';
20
20
 
21
21
  // Config
22
- import { distPath, autoComponents as autoComponentsConfig } from '../utils/config/config.js';
22
+ import { distPath, srcPath, autoComponents as autoComponentsConfig, components as componentsConfig } from '../utils/config/config.js';
23
23
 
24
24
 
25
25
  // DEFINE
@@ -76,13 +76,21 @@ class AutoComponents {
76
76
  // Separate into CSS-only and JS-requiring
77
77
  const jsComponents = customElements.filter(tag => !this.isCssOnly(tag));
78
78
 
79
- if (jsComponents.length === 0) {
80
- // No JS-requiring components — remove VB bundle script
79
+ // Check for Cook DSD components with companion JS hydration scripts
80
+ const cookDsdComponents = this.store._cookDsdComponents || {};
81
+ const cookJsComponents = jsComponents.filter(tag => cookDsdComponents[tag]);
82
+ this.injectCookDsdScripts(document, cookJsComponents);
83
+
84
+ // Filter out Cook DSD components from VB handling — they have their own scripts
85
+ const vbJsComponents = jsComponents.filter(tag => !cookDsdComponents[tag]);
86
+
87
+ if (vbJsComponents.length === 0) {
88
+ // No VB JS-requiring components — remove VB bundle script
81
89
  this.removeVbScript(document);
82
90
  this.store._autoComponentsStats.stripped++;
83
91
  } else if (this.store._autoComponentsManifest) {
84
92
  // We have a manifest — generate import map for only needed components
85
- this.injectImportMap(document, jsComponents);
93
+ this.injectImportMap(document, vbJsComponents);
86
94
  this.removeVbScript(document);
87
95
  this.store._autoComponentsStats.importMapped++;
88
96
  } else {
@@ -202,6 +210,33 @@ class AutoComponents {
202
210
  }
203
211
 
204
212
 
213
+ /**
214
+ * Inject <script type="module"> tags for Cook DSD components with companion JS.
215
+ * Looks for {componentName}.js alongside {componentName}.html in the components dir.
216
+ * @param {Document} document
217
+ * @param {string[]} cookJsComponents - Tag names of Cook DSD components on this page
218
+ */
219
+ injectCookDsdScripts(document, cookJsComponents) {
220
+ if (cookJsComponents.length === 0) return;
221
+
222
+ const jsPath = componentsConfig?.jsPath || 'assets/components';
223
+ const componentsPath = componentsConfig?.path || 'components';
224
+ const head = document.querySelector('head');
225
+ if (!head) return;
226
+
227
+ for (const tag of cookJsComponents) {
228
+ // Check if companion JS exists in src/components/
229
+ const jsFile = `${srcPath}/${componentsPath}/${tag}.js`;
230
+ if (!existsSync(path.resolve(jsFile))) continue;
231
+
232
+ // Add a module script pointing to the dist location
233
+ const script = document.createElement('script');
234
+ script.setAttribute('type', 'module');
235
+ script.setAttribute('src', `/${jsPath}/${tag}.js`);
236
+ head.appendChild(script);
237
+ }
238
+ }
239
+
205
240
  // EXPORT WRAPPER
206
241
  // -----------------------------
207
242
  static async export(opts) {
@@ -7,6 +7,7 @@
7
7
  * - JSON metadata in dist/api/{path}.json (for all pages)
8
8
  * - Atom feed at dist/feed.xml (from a configurable collection)
9
9
  * - llms.txt at dist/llms.txt (index of all content with markdown URLs)
10
+ * - llms-full.txt at dist/llms-full.txt (complete documentation in one file)
10
11
  */
11
12
 
12
13
  // IMPORTS
@@ -33,10 +34,11 @@ class GenerateFormats {
33
34
  json: true,
34
35
  feed: null,
35
36
  llmsTxt: true,
37
+ llmsFullTxt: false,
36
38
  ...formatsConfig,
37
39
  };
38
40
 
39
- this.stats = { markdown: 0, json: 0, feed: false, llmsTxt: false };
41
+ this.stats = { markdown: 0, json: 0, feed: false, llmsTxt: false, llmsFullTxt: false };
40
42
 
41
43
  // Init terminal logging
42
44
  Util.initLogging.call(this);
@@ -46,7 +48,7 @@ class GenerateFormats {
46
48
  // -----------------------------
47
49
  async init() {
48
50
  // Early Exit: No formats configured
49
- if (!this.config.markdown && !this.config.json && !this.config.feed && !this.config.llmsTxt) return;
51
+ if (!this.config.markdown && !this.config.json && !this.config.feed && !this.config.llmsTxt && !this.config.llmsFullTxt) return;
50
52
 
51
53
  // ADD TERMINAL SECTION HEADING
52
54
  Logger.persist.header(`\nGenerate Formats`);
@@ -75,6 +77,11 @@ class GenerateFormats {
75
77
  if (this.config.llmsTxt) {
76
78
  await this.generateLlmsTxt(indexFiles);
77
79
  }
80
+
81
+ // Generate llms-full.txt (complete documentation in one file)
82
+ if (this.config.llmsFullTxt) {
83
+ await this.generateLlmsFullTxt(indexFiles);
84
+ }
78
85
  } catch (err) {
79
86
  Util.customError(err, 'generate-formats.js');
80
87
  }
@@ -271,43 +278,169 @@ class GenerateFormats {
271
278
  }
272
279
 
273
280
  /**
274
- * Generate llms.txt listing all content with markdown URLs
281
+ * Collect page metadata from all index files for llms.txt generation.
282
+ * Reads HTML to extract title and description.
283
+ * @param {string[]} indexFiles - All index.html file paths
284
+ * @returns {Array<{title: string, description: string, url: string, mdUrl: string|null, section: string|null}>}
285
+ */
286
+ async collectPageMeta(indexFiles) {
287
+ const pages = [];
288
+ for (const filePath of indexFiles) {
289
+ const relativePath = filePath.replace(distPath, '');
290
+ const urlPath = relativePath.replace(/\/index\.html$/, '/').replace(/^$/, '/');
291
+ const mdSource = this.findMarkdownSource(urlPath);
292
+ const trimmedPath = urlPath.replace(/^\//, '').replace(/\/$/, '');
293
+
294
+ // Read HTML to extract title and description
295
+ let title = trimmedPath || 'index';
296
+ let description = '';
297
+ let section = null;
298
+ try {
299
+ const src = await fs.readFile(filePath, 'utf-8');
300
+ const dom = Util.jsdom.dom({ src });
301
+ const doc = dom.window.document;
302
+ const h1 = doc.querySelector('h1')?.textContent;
303
+ const titleTag = doc.querySelector('title')?.textContent;
304
+ const metaDesc = doc.querySelector('meta[name="description"]')?.getAttribute('content');
305
+ title = h1 || titleTag || title;
306
+ description = metaDesc || '';
307
+ } catch { /* use defaults */ }
308
+
309
+ // Check collection item for additional metadata
310
+ const collectionItem = this.findCollectionItem(urlPath);
311
+ if (collectionItem) {
312
+ title = collectionItem.title || title;
313
+ description = collectionItem.description || description;
314
+ section = collectionItem.section || null;
315
+ }
316
+
317
+ const mdUrl = mdSource
318
+ ? (trimmedPath ? `/md/${trimmedPath}/index.md` : `/md/index.md`)
319
+ : null;
320
+
321
+ pages.push({ title, description, url: urlPath, mdUrl, section });
322
+ }
323
+ return pages;
324
+ }
325
+
326
+ /**
327
+ * Generate llms.txt listing all content with markdown URLs.
328
+ * Enhanced with descriptions, section grouping, and AI instructions.
275
329
  * @param {string[]} indexFiles - All index.html file paths
276
330
  */
277
331
  async generateLlmsTxt(indexFiles) {
278
332
  const siteTitle = this.data.siteTitle || 'Site';
279
333
  const siteDescription = this.data.siteDescription || '';
280
334
  const siteUrl = this.data.siteUrl || '';
335
+ const llmsInstructions = this.data.llmsInstructions || '';
281
336
 
282
337
  let content = `# ${siteTitle}\n\n`;
283
338
  if (siteDescription) content += `> ${siteDescription}\n\n`;
284
339
 
285
- // List pages that have markdown sources
286
- const mdPages = [];
340
+ // AI instructions section (Stripe-style guidance for LLM agents)
341
+ if (llmsInstructions) {
342
+ content += `## Instructions for AI Agents\n\n${llmsInstructions.trim()}\n\n`;
343
+ }
344
+
345
+ // Collect page metadata
346
+ const pages = await this.collectPageMeta(indexFiles);
347
+ const mdPages = pages.filter(p => p.mdUrl);
348
+
349
+ if (mdPages.length) {
350
+ // Group by section if sections exist, otherwise flat list
351
+ const hasSections = mdPages.some(p => p.section);
352
+
353
+ if (hasSections) {
354
+ const sections = {};
355
+ const unsectioned = [];
356
+ for (const page of mdPages) {
357
+ if (page.section) {
358
+ if (!sections[page.section]) sections[page.section] = [];
359
+ sections[page.section].push(page);
360
+ } else {
361
+ unsectioned.push(page);
362
+ }
363
+ }
364
+
365
+ // Output sectioned pages
366
+ for (const [sectionName, sectionPages] of Object.entries(sections)) {
367
+ content += `## ${sectionName}\n\n`;
368
+ for (const page of sectionPages) {
369
+ const fullMdUrl = siteUrl ? `${siteUrl}${page.mdUrl}` : page.mdUrl;
370
+ const desc = page.description ? `: ${page.description}` : '';
371
+ content += `- [${page.title}](${fullMdUrl})${desc}\n`;
372
+ }
373
+ content += '\n';
374
+ }
375
+
376
+ // Output unsectioned pages
377
+ if (unsectioned.length) {
378
+ content += `## Content\n\n`;
379
+ for (const page of unsectioned) {
380
+ const fullMdUrl = siteUrl ? `${siteUrl}${page.mdUrl}` : page.mdUrl;
381
+ const desc = page.description ? `: ${page.description}` : '';
382
+ content += `- [${page.title}](${fullMdUrl})${desc}\n`;
383
+ }
384
+ }
385
+ } else {
386
+ // Flat list with descriptions
387
+ content += `## Content\n\n`;
388
+ for (const page of mdPages) {
389
+ const fullMdUrl = siteUrl ? `${siteUrl}${page.mdUrl}` : page.mdUrl;
390
+ const desc = page.description ? `: ${page.description}` : '';
391
+ content += `- [${page.title}](${fullMdUrl})${desc}\n`;
392
+ }
393
+ }
394
+ }
395
+
396
+ await fs.writeFile(path.resolve(`${distPath}/llms.txt`), content, 'utf-8');
397
+ this.stats.llmsTxt = true;
398
+ }
399
+
400
+ /**
401
+ * Generate llms-full.txt: concatenate all markdown page content into one file.
402
+ * Ideal for bulk ingestion by IDE tools and AI systems.
403
+ * @param {string[]} indexFiles - All index.html file paths
404
+ */
405
+ async generateLlmsFullTxt(indexFiles) {
406
+ const siteTitle = this.data.siteTitle || 'Site';
407
+ const siteDescription = this.data.siteDescription || '';
408
+ const llmsInstructions = this.data.llmsInstructions || '';
409
+
410
+ let content = `# ${siteTitle} — Complete Documentation\n\n`;
411
+ if (siteDescription) content += `> ${siteDescription}\n\n`;
412
+
413
+ // AI instructions
414
+ if (llmsInstructions) {
415
+ content += `## Instructions for AI Agents\n\n${llmsInstructions.trim()}\n\n---\n\n`;
416
+ }
417
+
418
+ // Collect pages and read their markdown content
287
419
  for (const filePath of indexFiles) {
288
420
  const relativePath = filePath.replace(distPath, '');
289
421
  const urlPath = relativePath.replace(/\/index\.html$/, '/').replace(/^$/, '/');
290
422
  const mdSource = this.findMarkdownSource(urlPath);
291
- if (mdSource) {
292
- const trimmedPath = urlPath.replace(/^\//, '').replace(/\/$/, '');
293
- // Find title from collection data or use path
423
+ if (!mdSource) continue;
424
+
425
+ try {
426
+ let mdContent = await fs.readFile(mdSource, 'utf-8');
427
+
428
+ // Strip YAML frontmatter for the concatenated output
429
+ mdContent = mdContent.replace(/^---[\s\S]*?---\n*/, '');
430
+
431
+ // Find title
294
432
  const collectionItem = this.findCollectionItem(urlPath);
433
+ const trimmedPath = urlPath.replace(/^\//, '').replace(/\/$/, '');
295
434
  const title = collectionItem?.title || trimmedPath || 'index';
296
- const mdUrl = trimmedPath ? `/md/${trimmedPath}/index.md` : `/md/index.md`;
297
- mdPages.push({ title, url: urlPath, mdUrl });
298
- }
299
- }
300
435
 
301
- if (mdPages.length) {
302
- content += `## Content\n\n`;
303
- for (const page of mdPages) {
304
- const fullMdUrl = siteUrl ? `${siteUrl}${page.mdUrl}` : page.mdUrl;
305
- content += `- [${page.title}](${fullMdUrl})\n`;
306
- }
436
+ content += `## ${title}\n\n`;
437
+ content += mdContent.trim();
438
+ content += '\n\n---\n\n';
439
+ } catch { /* skip unreadable files */ }
307
440
  }
308
441
 
309
- await fs.writeFile(path.resolve(`${distPath}/llms.txt`), content, 'utf-8');
310
- this.stats.llmsTxt = true;
442
+ await fs.writeFile(path.resolve(`${distPath}/llms-full.txt`), content, 'utf-8');
443
+ this.stats.llmsFullTxt = true;
311
444
  }
312
445
 
313
446
  /**
@@ -339,6 +472,7 @@ class GenerateFormats {
339
472
  if (this.stats.json) parts.push(`${this.stats.json} json`);
340
473
  if (this.stats.feed) parts.push('feed.xml');
341
474
  if (this.stats.llmsTxt) parts.push('llms.txt');
475
+ if (this.stats.llmsFullTxt) parts.push('llms-full.txt');
342
476
 
343
477
  if (parts.length) {
344
478
  this.loading.stop(`Generated ${chalk.magenta(parts.join(', '))} ${this.timer.end()}`);
@@ -0,0 +1,43 @@
1
+ /**
2
+ * @file prerender-code-blocks.js
3
+ * @description Pre-render <code-block> elements with Declarative Shadow DOM
4
+ * at build time using @profpowell/code-block/ssr.
5
+ *
6
+ * Runs AFTER the base64 restore step in build.js so code-block content
7
+ * is already decoded. Replaces each <code-block> with a DSD-powered
8
+ * version containing pre-highlighted code — zero client-side highlighting needed.
9
+ *
10
+ * Skips blocks with `src` attribute (runtime-loaded) and blocks already
11
+ * marked with `data-ssr`.
12
+ */
13
+
14
+ // IMPORTS
15
+ // -----------------------------
16
+ import { prerenderCodeBlocksInHtml } from '@profpowell/code-block/ssr'
17
+ import Util from '../utils/util/util.js'
18
+
19
+
20
+ // DEFINE
21
+ // -----------------------------
22
+ class PrerenderCodeBlocks {
23
+ constructor({ file, allowType, disallowType }) {
24
+ this.opts = { file, allowType, disallowType }
25
+ this.file = file
26
+ }
27
+
28
+ async init() {
29
+ const allowed = Util.isAllowedType(this.opts)
30
+ if (!allowed) return
31
+
32
+ // Early exit if no code-block elements present
33
+ if (!this.file.src.includes('<code-block')) return
34
+
35
+ this.file.src = prerenderCodeBlocksInHtml(this.file.src)
36
+ }
37
+
38
+ static async export(opts) {
39
+ return new PrerenderCodeBlocks(opts).init()
40
+ }
41
+ }
42
+
43
+ export default PrerenderCodeBlocks.export
@@ -16,6 +16,14 @@
16
16
  * - Template variables resolved with global data
17
17
  * - Consolidated into a single <style> in <head>
18
18
  * Authors can use native @scope and @layer for CSS scoping.
19
+ *
20
+ * DSD (Declarative Shadow DOM) components:
21
+ * If a component template contains <template shadowrootmode="open">,
22
+ * the component is rendered as a web component with Declarative Shadow DOM:
23
+ * - The custom element is preserved (not replaced with flat HTML)
24
+ * - Styles stay inside the shadow root (not extracted to <head>)
25
+ * - Native <slot> elements handle content projection
26
+ * - Optional companion .js files provide client-side hydration
19
27
  */
20
28
 
21
29
  // IMPORTS
@@ -165,7 +173,18 @@ class ReplaceComponents {
165
173
  }
166
174
 
167
175
  /**
168
- * Replace a component element with its template
176
+ * Check if a component template uses Declarative Shadow DOM.
177
+ * The presence of <template shadowrootmode> signals DSD intent.
178
+ * @param {string} template - Component template string
179
+ * @returns {boolean}
180
+ */
181
+ isDsdComponent(template) {
182
+ return /<template\s+shadowrootmode/i.test(template);
183
+ }
184
+
185
+ /**
186
+ * Replace a component element with its template.
187
+ * Routes to DSD or flat rendering based on template content.
169
188
  * @param {Object} componentInfo - Component information object
170
189
  */
171
190
  async replaceComponent(componentInfo) {
@@ -181,38 +200,102 @@ class ReplaceComponents {
181
200
  return;
182
201
  }
183
202
 
184
- // Extract <style> blocks from template (deduplicate per component)
185
- const { html: htmlTemplate, css } = this.extractStyles(template);
186
- if (css && !this.collectedStyles[componentName]) {
187
- // Resolve template variables in CSS with global data only
188
- this.collectedStyles[componentName] = this.renderTemplate(css, this.data);
203
+ // Branch: DSD components preserve the custom element with shadow DOM;
204
+ // flat components expand into plain HTML (existing behavior)
205
+ if (this.isDsdComponent(template)) {
206
+ this.renderDsdComponent(element, template, name, componentName);
207
+ } else {
208
+ this.renderFlatComponent(element, template, type, name, componentName);
189
209
  }
210
+ } catch (err) {
211
+ Util.customError(err, `replace-components.js: Error replacing ${name}`);
212
+ }
213
+ }
214
+
215
+ /**
216
+ * Render a DSD component: inject Declarative Shadow DOM into the custom element.
217
+ * - The custom element is preserved in the DOM
218
+ * - Styles stay inside the shadow root (not extracted to <head>)
219
+ * - Native <slot> elements handle content projection
220
+ * @param {Element} element - The custom element
221
+ * @param {string} template - Component template containing <template shadowrootmode>
222
+ * @param {string} name - Element tag name
223
+ * @param {string} componentName - Component template filename
224
+ */
225
+ renderDsdComponent(element, template, name, componentName) {
226
+ // Extract the <template shadowrootmode="..."> content via regex
227
+ // (avoids JSDOM template parsing quirks with document fragments)
228
+ const shadowMatch = template.match(
229
+ /<template\s+shadowrootmode="([^"]+)">([\s\S]*?)<\/template>/i
230
+ );
231
+ if (!shadowMatch) return;
232
+
233
+ const mode = shadowMatch[1]; // "open" or "closed"
234
+ let shadowContent = shadowMatch[2];
235
+
236
+ // Extract data from element attributes
237
+ const componentData = this.extractComponentData(element, 'custom-element');
238
+
239
+ // Merge with global data (component data takes precedence)
240
+ const mergedData = { ...this.data, ...componentData };
241
+
242
+ // Resolve template variables in shadow content
243
+ // Note: <slot> elements are NOT template variables — they stay as-is
244
+ shadowContent = this.renderTemplate(shadowContent, mergedData);
245
+
246
+ // Inject the DSD template as first child of the custom element
247
+ // Do NOT extract styles — they belong inside the shadow root for encapsulation
248
+ // Do NOT touch children — native <slot> handles content projection
249
+ element.insertAdjacentHTML('afterbegin',
250
+ `<template shadowrootmode="${mode}">${shadowContent}</template>`
251
+ );
252
+
253
+ // Record on store for auto-components awareness
254
+ if (!this.store._cookDsdComponents) this.store._cookDsdComponents = {};
255
+ this.store._cookDsdComponents[name] = componentName;
256
+
257
+ this.replaced.push(name);
258
+ }
259
+
260
+ /**
261
+ * Render a flat component: replace the element with expanded template HTML.
262
+ * This is the original behavior — styles extracted to <head>, element removed.
263
+ * @param {Element} element - The component element
264
+ * @param {string} template - Component template HTML
265
+ * @param {string} type - 'custom-element' or 'data-component'
266
+ * @param {string} name - Element tag/component name
267
+ * @param {string} componentName - Component template filename
268
+ */
269
+ renderFlatComponent(element, template, type, name, componentName) {
270
+ // Extract <style> blocks from template (deduplicate per component)
271
+ const { html: htmlTemplate, css } = this.extractStyles(template);
272
+ if (css && !this.collectedStyles[componentName]) {
273
+ // Resolve template variables in CSS with global data only
274
+ this.collectedStyles[componentName] = this.renderTemplate(css, this.data);
275
+ }
190
276
 
191
- // Extract data from element attributes
192
- const componentData = this.extractComponentData(element, type);
277
+ // Extract data from element attributes
278
+ const componentData = this.extractComponentData(element, type);
193
279
 
194
- // Extract named and default slot content from children
195
- this.extractSlots(element, componentData);
280
+ // Extract named and default slot content from children
281
+ this.extractSlots(element, componentData);
196
282
 
197
- // Merge with global data (component data takes precedence)
198
- const mergedData = { ...this.data, ...componentData };
283
+ // Merge with global data (component data takes precedence)
284
+ const mergedData = { ...this.data, ...componentData };
199
285
 
200
- // Replace template variables with data (style-free HTML only)
201
- const renderedContent = this.renderTemplate(htmlTemplate, mergedData);
286
+ // Replace template variables with data (style-free HTML only)
287
+ const renderedContent = this.renderTemplate(htmlTemplate, mergedData);
202
288
 
203
- // Insert rendered content and remove original element
204
- element.insertAdjacentHTML('afterend', renderedContent);
289
+ // Insert rendered content and remove original element
290
+ element.insertAdjacentHTML('afterend', renderedContent);
205
291
 
206
- // Transfer non-data attributes to the first valid replaced element
207
- this.transferAttributes(element, type);
292
+ // Transfer non-data attributes to the first valid replaced element
293
+ this.transferAttributes(element, type);
208
294
 
209
- // Remove the original component element
210
- element.remove();
295
+ // Remove the original component element
296
+ element.remove();
211
297
 
212
- this.replaced.push(name);
213
- } catch (err) {
214
- Util.customError(err, `replace-components.js: Error replacing ${name}`);
215
- }
298
+ this.replaced.push(name);
216
299
  }
217
300
 
218
301
  /**
@@ -96,8 +96,8 @@ class ReplaceExternalLinkProtocol {
96
96
  * @private
97
97
  */
98
98
  replaceMissingProtocol({file, scope, el}) {
99
- // Get source type (`href` or `src`)
100
- let srcType = el.href || el.src;
99
+ // Get source type (`href` or `src`) — use getAttribute for parser compatibility
100
+ let srcType = el.getAttribute('href') || el.getAttribute('src');
101
101
  // Early Exit: Tag does not have `[href]` or `[src]` or attribute value is empty string
102
102
  // Example: Someone adds an old-school anchor jump point: `<a id="jump-point"></a>`
103
103
  if (!srcType || srcType === '') return;
@@ -106,7 +106,7 @@ class ReplaceExternalLinkProtocol {
106
106
  // Only replace for `www` and `cdn` instances, unless user defined their own
107
107
  const domainTargets = replaceExternalLinkProtocol.match || Util.replaceExternalLinkProtocolDefaults;
108
108
  const isTargetMatch = domainTargets.indexOf(linkPath) > -1;
109
- const pathType = el.href ? 'href' : 'src';
109
+ const pathType = el.getAttribute('href') ? 'href' : 'src';
110
110
  // Update path
111
111
  if (isTargetMatch) this.replaceExternal(file, el, pathType);
112
112
  // Increment total counter
@@ -55,43 +55,53 @@ class ReplaceInclude {
55
55
  const allowed = Util.isAllowedType(this.opts);
56
56
  if (!allowed) return;
57
57
 
58
- // Store string source as traversable DOM
59
- let dom = Util.jsdom.dom({src: this.file.src});
60
- // Allow `[include]` or `[data-include]` by default
61
- const includeSelector = Util.getSelector(Util.attr.include);
62
- const includeItems = dom.window.document.querySelectorAll(includeSelector);
63
- this.total = includeItems.length;
64
-
65
- // Early Exit: No includes
66
- if (!includeItems) return;
58
+ // Early Exit: No includes in source
59
+ if (!this.file.src.includes('data-include') &&
60
+ !this.file.src.includes('<include-file')) return;
67
61
 
68
62
  // START LOGGING
69
63
  this.startLog();
70
64
 
71
- // Loop through each found include call and replace with fetched file source
72
- for (let item of includeItems) {
73
- await this.replaceInclude(item);
74
- }
75
-
76
- // Store updated file source
77
- this.file.src = Util.setSrc({dom});
78
-
79
- // Nested includes: if the injected content contains further includes,
80
- // resolve them recursively up to MAX_DEPTH to prevent infinite loops.
81
- if (this._depth < this.MAX_DEPTH) {
82
- const checkDom = Util.jsdom.dom({src: this.file.src});
83
- const nestedSelector = Util.getSelector(Util.attr.include);
84
- const nestedIncludes = checkDom.window.document.querySelectorAll(nestedSelector);
85
- if (nestedIncludes.length) {
86
- await new ReplaceInclude({
87
- file: this.file,
88
- store: this.store,
89
- allowType: this.allowType,
90
- disallowType: this.disallowType,
91
- excludePaths: this.excludePaths,
92
- _depth: this._depth + 1,
93
- }).init();
94
- }
65
+ // Resolve includes at the string level using regex.
66
+ // This avoids DOM parsing quirks (e.g., parsers moving elements
67
+ // out of <head>) and is faster than DOM-based resolution.
68
+ let changed = true;
69
+ while (changed && this._depth < this.MAX_DEPTH) {
70
+ changed = false;
71
+
72
+ // Match <include-file src="/path"></include-file>
73
+ this.file.src = await this.replacePattern(
74
+ this.file.src,
75
+ /<include-file\s+src="([^"]+)"[^>]*><\/include-file>/gi,
76
+ (match, srcPath) => srcPath,
77
+ () => { changed = true; }
78
+ );
79
+
80
+ // Match <... data-include="/path"...> (any element with data-include attribute)
81
+ this.file.src = await this.replacePattern(
82
+ this.file.src,
83
+ /<(\w+)\s[^>]*data-include="([^"]+)"[^>]*><\/\1>/gi,
84
+ (match, tag, srcPath) => srcPath,
85
+ () => { changed = true; }
86
+ );
87
+
88
+ // Match <... include="/path"...> (any element with include attribute)
89
+ this.file.src = await this.replacePattern(
90
+ this.file.src,
91
+ /<(\w+)\s[^>]*\binclude="([^"]+)"[^>]*><\/\1>/gi,
92
+ (match, tag, srcPath) => srcPath,
93
+ () => { changed = true; }
94
+ );
95
+
96
+ // Also handle self-closing: <meta data-include="/path">
97
+ this.file.src = await this.replacePattern(
98
+ this.file.src,
99
+ /<meta\s[^>]*data-include="([^"]+)"[^>]*>/gi,
100
+ (match, srcPath) => srcPath,
101
+ () => { changed = true; }
102
+ );
103
+
104
+ this._depth++;
95
105
  }
96
106
 
97
107
  // END LOGGING
@@ -99,7 +109,50 @@ class ReplaceInclude {
99
109
  }
100
110
 
101
111
 
102
- // REPLACE INDIV. INCLUDE
112
+ // STRING-LEVEL INCLUDE RESOLUTION
113
+ // -----------------------------
114
+ /**
115
+ * @description Replace all matches of a pattern with fetched file content
116
+ * @param {string} src - The source HTML string
117
+ * @param {RegExp} pattern - Regex to match include markers
118
+ * @param {Function} pathExtractor - Function that extracts the file path from regex groups
119
+ * @param {Function} onReplace - Callback when a replacement is made
120
+ * @returns {string} Updated source
121
+ */
122
+ async replacePattern(src, pattern, pathExtractor, onReplace) {
123
+ const matches = [...src.matchAll(pattern)];
124
+ if (!matches.length) return src;
125
+
126
+ // Process matches in reverse order to preserve string positions
127
+ for (let i = matches.length - 1; i >= 0; i--) {
128
+ const match = matches[i];
129
+ const filePath = pathExtractor(...match);
130
+ const content = await this.getIncludeContent(filePath);
131
+ src = src.substring(0, match.index) + content + src.substring(match.index + match[0].length);
132
+ this.total++;
133
+ onReplace();
134
+ }
135
+ return src;
136
+ }
137
+
138
+ /**
139
+ * @description Get include file content (with caching)
140
+ * @param {string} filePath - The include path (e.g., "/includes/head.html")
141
+ * @returns {string} File content
142
+ */
143
+ async getIncludeContent(filePath) {
144
+ const fullPath = path.resolve(`${srcPath}/${filePath}`);
145
+
146
+ // Check cache
147
+ const cached = this.store.cachedIncludes[fullPath];
148
+ if (cached !== undefined && cached !== null) return cached;
149
+
150
+ // Fetch and cache
151
+ return await this.fetchIncludeSrc(fullPath);
152
+ }
153
+
154
+
155
+ // REPLACE INDIV. INCLUDE (legacy DOM-based — kept for backward compat)
103
156
  // -----------------------------
104
157
  /**
105
158
  * @description Replace include with corresponding source code
@@ -130,14 +183,9 @@ class ReplaceInclude {
130
183
  else content = await this.fetchIncludeSrc(includePath);
131
184
 
132
185
  // ADD CONTENT TO DOM
133
- // Add included content in DOM before placeholder element
134
- el.insertAdjacentHTML('afterend', content);
135
- // Add any attributes that were on the include element to the first replaced DOM element (that is valid)
136
- // A 'valid' element is a non- style/script/template etc. element. See the check in the method for the full list
137
- // NOTE: If an include has multiple 'top-level' elements, they will be applied to the first one
138
- this.addAttributesToReplacedDOM(el);
139
- // Remove placeholder element from DOM (`<div include="/includes/xxxx"></div>`)
140
- el.remove();
186
+ // Replace the include element with the fetched content using outerHTML.
187
+ // This keeps content in the correct DOM context (e.g., <head> stays in <head>).
188
+ el.outerHTML = content;
141
189
  }
142
190
  catch (err) {
143
191
  Util.customError(err, `replace-includes.js`);
@@ -195,7 +243,11 @@ class ReplaceInclude {
195
243
  for (let i=0; i<el.attributes.length; i++) {
196
244
  const name = el.attributes[i].name;
197
245
  const value = el.attributes[i].value;
198
- const isValidAttr = Util.attr.include.indexOf(name) === -1;
246
+ const includeFileOwnAttrs = ['src', 'mode', 'lazy', 'allow-scripts'];
247
+ const isIncludeFile = el.tagName === 'INCLUDE-FILE';
248
+ const isValidAttr = isIncludeFile
249
+ ? includeFileOwnAttrs.indexOf(name) === -1
250
+ : Util.attr.include.indexOf(name) === -1;
199
251
  if (isValidAttr) targetEl.setAttribute(name, value);
200
252
  }
201
253
  }
@@ -226,6 +278,12 @@ class ReplaceInclude {
226
278
  * @private
227
279
  */
228
280
  hasAttribute(el, attrs) {
281
+ // Handle <include-file src="..."> elements
282
+ if (el.tagName === 'INCLUDE-FILE') {
283
+ const srcVal = el.getAttribute('src');
284
+ return srcVal ? { type: 'src', path: srcVal } : false;
285
+ }
286
+ // Handle [include] / [data-include] elements
229
287
  let tmpArr = [];
230
288
  if (typeof attrs === 'string') tmpArr.push({ type: Util.attr.include, path: el.getAttribute(Util.attr.include) });
231
289
  else attrs.forEach(a => tmpArr.push({ type: a, path: el.getAttribute(a) }));
@@ -83,6 +83,8 @@ const defaultConfig = {
83
83
  // Explicit mapping of element names to template files
84
84
  // If not mapped, uses element name as filename (e.g., 'header' -> 'header.html')
85
85
  mapping: {},
86
+ // Path in dist where DSD component JS hydration scripts are served from
87
+ jsPath: 'assets/components',
86
88
  },
87
89
 
88
90
  // Markdown: Convert .md files to HTML with front matter support
@@ -130,6 +132,7 @@ const defaultConfig = {
130
132
  json: true,
131
133
  feed: null,
132
134
  llmsTxt: true,
135
+ llmsFullTxt: false,
133
136
  },
134
137
 
135
138
  // Fragments: Generate content-only HTML fragments for SPA navigation
@@ -6,7 +6,7 @@ import cliCursor from 'cli-cursor';
6
6
  import cliSpinners from 'cli-spinners';
7
7
  import v8 from 'node:v8';
8
8
  import { lstatSync, readdirSync } from 'node:fs';
9
- import { JSDOM } from 'jsdom';
9
+ import { parseHTML } from 'linkedom';
10
10
 
11
11
  import Logger from '../logger/logger.js';
12
12
  import Spinner from '../spinner/spinner.js';
@@ -17,12 +17,14 @@ import { activeLink, convertPageToDirectory, includeAttr, inlineAttr } from '../
17
17
 
18
18
  const cwd = process.cwd();
19
19
 
20
- // JSDOM CONFIG
20
+ // DOM CONFIG
21
21
  // ----------------------------------
22
- // https://github.com/jsdom/jsdom
22
+ // Using LinkeDOM for fast, lenient HTML parsing that doesn't enforce
23
+ // content model rules (allows custom elements in <head>, etc.)
24
+ // https://github.com/WebReflection/linkedom
23
25
  const jsdom = {
24
26
  baseUrl: 'https://localhost',
25
- dom: newJSDOM,
27
+ dom: newDOM,
26
28
  frag: newFrag,
27
29
  }
28
30
 
@@ -33,6 +35,7 @@ const attr = {
33
35
  active: convertToKebab(activeLink && activeLink.activeState, 'space') || 'active',
34
36
  activeParent: convertToKebab(activeLink && activeLink.parentState, 'space') || 'active-parent',
35
37
  include: includeAttr ? [includeAttr, `data-${includeAttr}`] : ['include', 'data-include'],
38
+ includeFile: 'include-file[src]',
36
39
  inline: inlineAttr ? [inlineAttr, `data-${inlineAttr}`] : ['inline', 'data-inline'],
37
40
  }
38
41
 
@@ -380,11 +383,13 @@ function fakePromise(ms, throwError) {
380
383
  * @private
381
384
  */
382
385
  function getFileName(path, distPath) {
386
+ if (!path || typeof path !== 'string') return '';
383
387
  let splitOnSlash = path.split('/');
384
388
  splitOnSlash = splitOnSlash.filter(s => s !== '');
385
389
  let lastPart = splitOnSlash[splitOnSlash.length-1];
390
+ if (!lastPart) return '';
386
391
  let fileName = lastPart.split('.')[0];
387
- if (fileName === 'index') fileName = splitOnSlash[splitOnSlash.length-2];
392
+ if (fileName === 'index') fileName = splitOnSlash[splitOnSlash.length-2] || '/';
388
393
  if (fileName === distPath) fileName = '/';
389
394
  return fileName;
390
395
  }
@@ -545,39 +550,26 @@ function isExtension(fileName, target) {
545
550
  * @property {Object} [options] - Optional JSDOM options config object
546
551
  * @returns {Object}
547
552
  */
548
- function newJSDOM({src,options}) {
549
- const opts = options || { url: jsdom.baseUrl };
550
-
551
- // Protect <code-block> elements from JSDOM parsing.
552
- // JSDOM treats custom elements as generic HTML and can mangle their
553
- // text content (especially plain JS/CSS) into attribute-like tokens.
554
- // We replace them with comment placeholders before parsing, then restore after.
555
- const codeBlockStore = [];
556
- const protectedSrc = src.replace(/<code-block\b[\s\S]*?<\/code-block>/gi, (match) => {
557
- const index = codeBlockStore.length;
558
- codeBlockStore.push(match);
559
- return `<!--COOK_CB_${index}-->`;
560
- });
561
-
562
- const dom = new JSDOM(protectedSrc, opts);
563
-
564
- // Attach the code-block store to the dom object so setSrc can restore them
565
- if (codeBlockStore.length) {
566
- dom._codeBlockStore = codeBlockStore;
567
- }
568
-
569
- return dom;
553
+ function newDOM({src, options}) {
554
+ // LinkeDOM's parseHTML returns { document, window, ... }
555
+ // We wrap it to provide a compatible interface for existing plugins
556
+ const parsed = parseHTML(src);
557
+ return {
558
+ window: { document: parsed.document },
559
+ serialize: () => parsed.document.toString(),
560
+ _document: parsed.document,
561
+ };
570
562
  }
571
563
 
572
564
  /**
573
- * @description Get a new JSDOM fragment from the passed in string source
574
- * @docs https://github.com/jsdom/jsdom
575
- * @param {Object} opts - The arguments object
576
- * @property {String} fileSource - The source to make a traversable document from
577
- * @returns {Object}
565
+ * @description Get a new DOM fragment from the passed in string source
566
+ * @param {String} src - The HTML source to parse as a fragment
567
+ * @returns {Object} DocumentFragment-like object
578
568
  */
579
569
  function newFrag(src) {
580
- return JSDOM.fragment(src);
570
+ const { document } = parseHTML(`<body>${src}</body>`);
571
+ // Return the body element as a fragment-like container
572
+ return document.body;
581
573
  }
582
574
 
583
575
  /**
@@ -649,13 +641,9 @@ async function runFileLoop(files, method) {
649
641
  function setSrc({dom, path}) {
650
642
  let result;
651
643
 
652
- // Dom Fragment
644
+ // Dom Fragment (from newFrag — a body element used as container)
653
645
  if (!dom.window) {
654
- const XMLSerializer = new JSDOM('').window.XMLSerializer;
655
- const domString = new XMLSerializer().serializeToString(dom)
656
- result = domString
657
- .replace(/ xmlns="http:\/\/www.w3.org\/1999\/xhtml"/gmi, '')
658
- .replace(/ns(\d)*?:(?:href)/gmi, 'href');
646
+ result = dom.innerHTML;
659
647
  }
660
648
  // Full HTML document
661
649
  else {
@@ -666,11 +654,6 @@ function setSrc({dom, path}) {
666
654
  else result = `${document.head.innerHTML}${document.body.innerHTML}`;
667
655
  }
668
656
 
669
- // Restore protected <code-block> elements
670
- if (dom._codeBlockStore) {
671
- result = result.replace(/<!--COOK_CB_(\d+)-->/g, (_, i) => dom._codeBlockStore[i]);
672
- }
673
-
674
657
  return result;
675
658
  }
676
659