cook-ssg 2.0.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.
Files changed (37) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +445 -0
  3. package/bin/cook.js +66 -0
  4. package/package.json +75 -0
  5. package/patches/jsdom-fetch-fix.js +52 -0
  6. package/scripts/build.js +212 -0
  7. package/scripts/dev.js +119 -0
  8. package/scripts/plugins/apply-template.js +226 -0
  9. package/scripts/plugins/auto-components.js +215 -0
  10. package/scripts/plugins/bundle.js +338 -0
  11. package/scripts/plugins/copy-src.js +89 -0
  12. package/scripts/plugins/create-dir-from-file.js +144 -0
  13. package/scripts/plugins/create-dist.js +55 -0
  14. package/scripts/plugins/custom-plugins.js +118 -0
  15. package/scripts/plugins/declarative-shadow-dom.js +164 -0
  16. package/scripts/plugins/escape-code-blocks.js +54 -0
  17. package/scripts/plugins/generate-formats.js +361 -0
  18. package/scripts/plugins/generate-fragments.js +126 -0
  19. package/scripts/plugins/generate-sitemap-xml.js +216 -0
  20. package/scripts/plugins/minify-src.js +253 -0
  21. package/scripts/plugins/optimize-images.js +389 -0
  22. package/scripts/plugins/process-html-frontmatter.js +75 -0
  23. package/scripts/plugins/process-markdown.js +384 -0
  24. package/scripts/plugins/repeat-collection.js +296 -0
  25. package/scripts/plugins/replace-components.js +496 -0
  26. package/scripts/plugins/replace-external-link-protocol.js +171 -0
  27. package/scripts/plugins/replace-include.js +273 -0
  28. package/scripts/plugins/replace-inline.js +217 -0
  29. package/scripts/plugins/replace-template-strings.js +121 -0
  30. package/scripts/plugins/set-active-links.js +175 -0
  31. package/scripts/utils/config/config.js +277 -0
  32. package/scripts/utils/get-src/get-src.js +241 -0
  33. package/scripts/utils/logger/logger.js +47 -0
  34. package/scripts/utils/performance/performance.js +35 -0
  35. package/scripts/utils/spinner/spinner.js +112 -0
  36. package/scripts/utils/timer/timer.js +40 -0
  37. package/scripts/utils/util/util.js +719 -0
@@ -0,0 +1,144 @@
1
+ /**
2
+ * @file create-dir-from-file.js
3
+ * @description Change all `xxxx.html` pages into `xxxx/index.html` versions so you
4
+ * don't need to show extensions in the url
5
+ */
6
+
7
+ // IMPORT
8
+ // -----------------------------
9
+ import chalk from 'chalk';
10
+ import fs from 'fs-extra';
11
+ import utils from '../utils/util/util.js';
12
+ import Logger from '../utils/logger/logger.js';
13
+ import Spinner from '../utils/spinner/spinner.js';
14
+ import Timer from '../utils/timer/timer.js';
15
+ import { convertPageToDirectory, distPath } from '../utils/config/config.js';
16
+ import { getSrcConfig } from '../utils/get-src/get-src.js';
17
+
18
+ const cwd = process.cwd();
19
+
20
+
21
+ // DEFINE
22
+ // -----------------------------
23
+ /**
24
+ * @description Change all `xxxx.html` pages into `xxxx/index.html` versions so you
25
+ * don't need to show extensions in the url
26
+ * @param {Object} obj - Deconstructed options object
27
+ * @property {Object} obj.files - The current project files to affect
28
+ * @property {Array} [obj.allowType] - Allowed file types (Opt-in)
29
+ * @property {Array} [obj.disallowType] - Disallowed file types (Opt-out)
30
+ * @property {Array} [obj.excludePaths] - Disallowed certain files (Opt-out)
31
+ */
32
+ class CreateDirFromFile {
33
+ constructor({files, allowType, disallowType, excludePaths = []}) {
34
+ this.opts = {files, allowType, disallowType, excludePaths};
35
+ this.files = files;
36
+ this.allowType = allowType;
37
+ this.disallowType = disallowType;
38
+ this.excludePaths = excludePaths;
39
+ }
40
+
41
+ // INIT
42
+ // -----------------------------
43
+ // Note: `process.env.DEV_CHANGED_PAGE` is defined in `browserSync.watch()` in dev.js
44
+ async init() {
45
+ // Early Exit: User opted out of this plugin
46
+ if (convertPageToDirectory.disabled) return;
47
+
48
+ // Destructure options
49
+ const { files } = this;
50
+
51
+ // Show terminal message: Start
52
+ Logger.persist.header(`\nCreate Directories from Files`);
53
+
54
+ // Start timer
55
+ const timer = new Timer();
56
+ timer.start();
57
+
58
+ // Start percentage loading
59
+ const loading = new Spinner();
60
+ loading.start(`Create Directory from File`);
61
+ loading.count = 0;
62
+
63
+ // CONVERT EACH ALLOWED .HTML PAGE TO DIRECTORY
64
+ await utils.promiseAll(
65
+ files,
66
+ f => (this.createDirectory)(f, loading, this.opts),
67
+ progress => {
68
+ // Remove manual, static .html pages in `/docs` so they don't appear in the total # display
69
+ if (loading.label) {
70
+ loading.count += 1;
71
+ loading.updateAsPercentage(files[loading.count-1], loading.count, loading.total, true);
72
+ }
73
+ else loading.total -= 1;
74
+ }
75
+ );
76
+
77
+ // End: Loading terminal message
78
+ loading.stop(`Directories Created (${loading.count}) ${timer.end()}`);
79
+ }
80
+
81
+
82
+ // HELPER METHODS
83
+ // -----------------------------
84
+
85
+ /**
86
+ * @description TODO
87
+ * @param {*} fileName
88
+ * @param {*} filesArr
89
+ * @param {*} allowType
90
+ * @param {*} disallowType
91
+ * @param {*} excludePaths
92
+ * @param {*} loading
93
+ */
94
+ async createDirectory(fileName, loading, { files, allowType, disallowType, excludePaths }) {
95
+ // Get file's meta info (ext,name,path)
96
+ const file = await getSrcConfig({fileName, excludeSrc: true });
97
+
98
+ // Early Exit: File type not allowed
99
+ const allowed = utils.isAllowedType({file, allowType, disallowType});
100
+ if (!allowed) return;
101
+
102
+ // Early Exit: Do not create directory if current file is an index.html page
103
+ if (file.name === 'index') return;
104
+
105
+ // Early Exit: Path includes excluded pattern
106
+ // For example, we don't want to convert the site index file (homepage)
107
+ // ---
108
+ // Did user add excluded paths and there are defaults passed into this method?
109
+ const combinedExcludePaths = [...excludePaths, ...convertPageToDirectory.excludePaths];
110
+ const matchedExcludePath = combinedExcludePaths && combinedExcludePaths.filter(str => file.path.includes(str));
111
+ const matchedExcludePathLen = matchedExcludePath.length;
112
+ if (matchedExcludePathLen) return;
113
+
114
+ // Get file path without extension
115
+ const filePath = file.path.split('.')[0];
116
+
117
+ // CREATE NEW DIRECTORY IN /DIST
118
+ await fs.mkdirp(filePath);
119
+
120
+ // MOVE PAGE TO NEW DIRECTORY
121
+ // Move xxxx.html file to new directory xxxx/index.html
122
+ await fs.rename(`${filePath}.html`, `${filePath}/index.html`)
123
+
124
+ // UPDATE FILE PATH TO NEW DIST LOCATION
125
+ // In order to update the pages' new location, instead of the old,
126
+ // we need to update the /dist path to reflect the new, directory location
127
+ const index = files.indexOf(fileName);
128
+ files[index] = files[index].replace(/\.html$/, '/index.html').replace(/\/index\/index\.html$/, '/index.html')
129
+
130
+ // Loading message: Update
131
+ loading.label = `/${filePath}.html - Converted to [directory]: ${ chalk.green(`${filePath}/index.html`) }`;
132
+ }
133
+
134
+ // EXPORT WRAPPER
135
+ // -----------------------------
136
+ // Export function wrapper instead of class for `build.js` simplicity
137
+ static async export(opts) {
138
+ return new CreateDirFromFile(opts).init();
139
+ }
140
+ }
141
+
142
+ // EXPORT
143
+ // -----------------------------
144
+ export default CreateDirFromFile.export;
@@ -0,0 +1,55 @@
1
+ /**
2
+ * @file create-dist.js
3
+ * @description Remove `/dist` and recreate it
4
+ */
5
+
6
+ // IMPORT
7
+ // -----------------------------
8
+ import chalk from 'chalk';
9
+ import fs from 'fs-extra';
10
+ import { rimraf } from 'rimraf';
11
+ import Logger from '../utils/logger/logger.js';
12
+ import Util from '../utils/util/util.js';
13
+
14
+ const cwd = process.cwd();
15
+
16
+ // Config
17
+ import { distPath } from '../utils/config/config.js';
18
+
19
+ // DEFINE
20
+ // -----------------------------
21
+ class CreateDist {
22
+ constructor() {}
23
+
24
+ // INIT
25
+ // -----------------------------
26
+ // Note: `process.env.DEV_CHANGED_PAGE` is defined in `browserSync.watch()` in dev.js
27
+ async init() {
28
+ // Early Exit: Do not create `/dist` if only a single page was updated
29
+ if (process.env.DEV_CHANGED_PAGE) return;
30
+
31
+ // Show terminal message: Start
32
+ Logger.persist.header(`\nCreate /${distPath}`);
33
+
34
+ // Remove `/dist` (fails silently if not there as that is the intended result)
35
+ rimraf.sync(distPath);
36
+ // Make fresh '/dist' folder
37
+ await fs.mkdir(distPath).catch(Util.customError);
38
+
39
+ // Show terminal message: Done
40
+ Logger.persist.success (`/${distPath} created`);
41
+ }
42
+
43
+ // EXPORT WRAPPER
44
+ // -----------------------------
45
+ // Export function wrapper instead of class for `build.js` simplicity
46
+ static async export(opts) {
47
+ return new CreateDist(opts).init();
48
+ }
49
+ }
50
+
51
+
52
+ // EXPORT
53
+ // -----------------------------
54
+ // module.exports = CreateDist.export;
55
+ export default CreateDist.export;
@@ -0,0 +1,118 @@
1
+ /**
2
+ * @file custom-plugins.js
3
+ * @description Runs custom plugins defined outside of the build repo
4
+ */
5
+
6
+ // IMPORT
7
+ // -----------------------------
8
+ import Logger from '../utils/logger/logger.js';
9
+ import Util from '../utils/util/util.js';
10
+ import { pluginPath } from '../utils/config/config.js';
11
+
12
+ const cwd = process.cwd();
13
+
14
+ // DEFINE
15
+ // -----------------------------
16
+ /**
17
+ * @description Runs custom plugins defined outside of the build repo
18
+ * @param {Object} obj - Deconstructed options object
19
+ * @property {Object} obj.file - The current file's info (name, extension, path, src, etc.) if a per-file plugin or all the allowed files if a `before` or `after` file loop plugin
20
+ * @property {Object} obj.store - The build process' own data store object we'll add the cached inline-file content to
21
+ * @property {Object} obj.data - The user's custom data from the `data.js` config file, so they can access it in their custom plugins
22
+ * @property {Boolean} obj.log - User opt-in to show the full logging in the terminal or not
23
+ * @property {Object} obj.plugins - The set of custom-user plugins to run for this instance.
24
+ * These are pulled from the `main.js` config file, and are run in 3 build positions: `before`, `after` and during the files loop (`default`).
25
+ * Note: The user must create and export the plugin as an ES6 class
26
+ */
27
+ class CustomPlugins {
28
+ constructor({file, store, data = {}, log, plugins}) {
29
+ this.file = file;
30
+ this.store = store;
31
+ this.data = data;
32
+ this.log = log;
33
+ this.plugins = plugins;
34
+
35
+ // Store # of plugins
36
+ this.total = plugins && plugins.length || 0;
37
+ }
38
+
39
+ // INIT
40
+ // -----------------------------
41
+ // Note: `process.env.DEV_CHANGED_PAGE` is defined in `browserSync.watch()` in dev.js
42
+ async init() {
43
+ // Early Exit: No Plugins
44
+ if (!this.plugins) return;
45
+
46
+ // Show terminal message: Start
47
+ // Note: only shown for 'Before' and 'After' cases, not inside the file loop
48
+ if (this.log && this.total) Logger.persist.header(`\nCustom User Plugins: ${this.log} (${this.total})`);
49
+
50
+ // Execute each user plugin
51
+ // NOTE: Using recursion instead of `util.promiseAll` since we want
52
+ // each plugin to run schronously. Their internal plugin code can
53
+ // await async code, though.
54
+ await this.recursePlugins(0);
55
+
56
+ // Add spacing in terminal
57
+ if (process.env.NODE_ENV !== 'development' && this.log === 'After') console.log('\n');
58
+ }
59
+
60
+
61
+ // HELPER METHODS
62
+ // -----------------------------
63
+
64
+ async recursePlugins(index) {
65
+ // Stop recursion if no more plugins
66
+ if (!this.plugins[index]) return;
67
+
68
+ // Show terminal message: Plugin Start
69
+ if (this.log) Logger.info(this.plugins[index]);
70
+
71
+ // Get destructured parts
72
+ const {file, data} = this;
73
+
74
+ // GET PLUGIN FILE'S SOURCE
75
+ // If the first request, fetch it via `import()` and cache it. Use cache for all subsequent requests
76
+ // ---
77
+ // USE CACHED PLUGIN CODE, IF FOUND
78
+ let plugin;
79
+ const pathToPluginFile = `${cwd}/${pluginPath}/${this.plugins[index]}.js`;
80
+ const cachedTarget = this.store.plugins[pathToPluginFile];
81
+ if ([undefined, null].indexOf(cachedTarget) === -1) {
82
+ plugin = cachedTarget;
83
+ }
84
+ // OTHERWISE, FETCH THE PLUGIN FILE'S SOURCE AND CACHE IT
85
+ else {
86
+ // Get plugin source
87
+ plugin = await import(`${cwd}/${pluginPath}/${this.plugins[index]}.js`);
88
+ // Add it to lookup cache
89
+ this.store.plugins[pathToPluginFile] = plugin;
90
+ }
91
+
92
+ // RUN PLUGIN
93
+ // Run plugin's `init()` method (since it might be async - constructors can't be async)
94
+ // Note: Using try..catch instead of `.init().catch()`, since the init method may not be set as async from the user.
95
+ try {
96
+ await new plugin[Object.keys(plugin)[0]]({file, data}).init();
97
+ }
98
+ catch (err) {
99
+ Util.customError(err, `Plugin: ${this.plugins[index]}.js`)
100
+ }
101
+
102
+ // GO TO NEXT PLUGIN
103
+ await this.recursePlugins(index+=1);
104
+ };
105
+
106
+
107
+ // EXPORT WRAPPER
108
+ // -----------------------------
109
+ // Export function wrapper instead of class for `build.js` simplicity
110
+ static async export(opts) {
111
+ return new CustomPlugins(opts).init();
112
+ }
113
+ }
114
+
115
+
116
+ // EXPORT
117
+ // -----------------------------
118
+ export default CustomPlugins.export;
@@ -0,0 +1,164 @@
1
+ /**
2
+ * @file declarative-shadow-dom.js
3
+ * @description Pre-render Declarative Shadow DOM for web components.
4
+ *
5
+ * Scans built HTML for Shadow DOM component tags, looks up pre-rendered
6
+ * shadow DOM content from a manifest, and injects
7
+ * <template shadowrootmode="open"> with the content.
8
+ *
9
+ * This eliminates FOUC for Shadow DOM components and makes their content
10
+ * visible to search engines without waiting for JS.
11
+ *
12
+ * Prerequisites:
13
+ * - VB components need: if (!this.shadowRoot) this.attachShadow({ mode: 'open' })
14
+ * - A DSD manifest mapping tag names to shadow DOM HTML
15
+ *
16
+ * Components that use Light DOM (layout-*, tab-set, accordion-wc, tool-tip)
17
+ * don't need DSD — they already work without JS.
18
+ */
19
+
20
+ // IMPORTS
21
+ // -----------------------------
22
+ import chalk from 'chalk';
23
+ import { existsSync } from 'node:fs';
24
+ import { promises as fs } from 'node:fs';
25
+ import path from 'node:path';
26
+ import Util from '../utils/util/util.js';
27
+
28
+ // Config
29
+ import { distPath, dsd as dsdConfig } from '../utils/config/config.js';
30
+
31
+
32
+ // DEFINE
33
+ // -----------------------------
34
+ class DeclarativeShadowDom {
35
+ constructor({ file, store, allowType, disallowType }) {
36
+ this.opts = { file, allowType, disallowType };
37
+ this.file = file;
38
+ this.store = store;
39
+
40
+ this.config = {
41
+ enabled: false,
42
+ // Path to DSD manifest JSON (tag → shadow DOM HTML)
43
+ manifest: null,
44
+ // User overrides
45
+ ...dsdConfig,
46
+ };
47
+
48
+ // Track stats
49
+ if (!this.store._dsdStats) {
50
+ this.store._dsdStats = { total: 0 };
51
+ }
52
+ }
53
+
54
+ // INIT
55
+ // -----------------------------
56
+ async init() {
57
+ // Early Exit: Disabled
58
+ if (!this.config.enabled) return;
59
+
60
+ // Early Exit: File type not allowed
61
+ const allowed = Util.isAllowedType(this.opts);
62
+ if (!allowed) return;
63
+
64
+ // Load manifest once
65
+ await this.loadManifest();
66
+
67
+ // Early Exit: No manifest available
68
+ if (!this.store._dsdManifest) return;
69
+
70
+ // Parse HTML
71
+ const dom = Util.jsdom.dom({ src: this.file.src });
72
+ const document = dom.window.document;
73
+
74
+ // Find all custom elements that have DSD templates
75
+ const manifest = this.store._dsdManifest;
76
+ let injected = 0;
77
+
78
+ for (const [tagName, shadowHtml] of Object.entries(manifest)) {
79
+ const elements = document.querySelectorAll(tagName);
80
+ for (const el of elements) {
81
+ // Skip if element already has a declarative shadow root
82
+ if (el.querySelector('template[shadowrootmode]')) continue;
83
+
84
+ // Resolve any dynamic content in the shadow template
85
+ const resolvedHtml = this.resolveTemplate(shadowHtml, el);
86
+
87
+ // Inject the DSD template as the first child
88
+ el.insertAdjacentHTML('afterbegin',
89
+ `<template shadowrootmode="open">${resolvedHtml}</template>`
90
+ );
91
+ injected++;
92
+ }
93
+ }
94
+
95
+ if (injected > 0) {
96
+ this.file.src = Util.setSrc({ dom });
97
+ this.store._dsdStats.total += injected;
98
+ }
99
+ }
100
+
101
+ /**
102
+ * Load the DSD manifest (JSON: tag → shadow DOM HTML)
103
+ * Cached after first load.
104
+ */
105
+ async loadManifest() {
106
+ // Already loaded (or determined to not exist)
107
+ if (this.store._dsdManifest !== undefined) return;
108
+
109
+ if (!this.config.manifest) {
110
+ this.store._dsdManifest = null;
111
+ return;
112
+ }
113
+
114
+ const manifestPath = path.resolve(`${distPath}/${this.config.manifest}`);
115
+ if (!existsSync(manifestPath)) {
116
+ // Also check relative to cwd
117
+ const cwdPath = path.resolve(this.config.manifest);
118
+ if (!existsSync(cwdPath)) {
119
+ this.store._dsdManifest = null;
120
+ return;
121
+ }
122
+ try {
123
+ const content = await fs.readFile(cwdPath, 'utf-8');
124
+ this.store._dsdManifest = JSON.parse(content);
125
+ } catch {
126
+ this.store._dsdManifest = null;
127
+ }
128
+ return;
129
+ }
130
+
131
+ try {
132
+ const content = await fs.readFile(manifestPath, 'utf-8');
133
+ this.store._dsdManifest = JSON.parse(content);
134
+ } catch {
135
+ this.store._dsdManifest = null;
136
+ }
137
+ }
138
+
139
+ /**
140
+ * Resolve dynamic content in a shadow template based on element attributes.
141
+ * Replaces ${attr:name} with the element's attribute value.
142
+ * @param {string} template - Shadow DOM HTML template
143
+ * @param {Element} el - The host element
144
+ * @returns {string} Resolved HTML
145
+ */
146
+ resolveTemplate(template, el) {
147
+ return template.replace(/\$\{attr:([^}]+)\}/g, (match, attrName) => {
148
+ const value = el.getAttribute(attrName.trim());
149
+ return value !== null ? value : '';
150
+ });
151
+ }
152
+
153
+
154
+ // EXPORT WRAPPER
155
+ // -----------------------------
156
+ static async export(opts) {
157
+ return new DeclarativeShadowDom(opts).init();
158
+ }
159
+ }
160
+
161
+
162
+ // EXPORT
163
+ // -----------------------------
164
+ export default DeclarativeShadowDom.export;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * @file escape-code-blocks.js
3
+ * @description HTML-escape the content of <code-block> elements at build time.
4
+ *
5
+ * Uses regex to find <code-block data-escape> and encodes the content as
6
+ * base64 in a data attribute, preventing JSDOM from mangling it.
7
+ * A post-JSDOM step in build.js decodes and restores the content.
8
+ */
9
+
10
+ // IMPORTS
11
+ // -----------------------------
12
+ import Util from '../utils/util/util.js';
13
+
14
+
15
+ // DEFINE
16
+ // -----------------------------
17
+ class EscapeCodeBlocks {
18
+ constructor({ file, allowType, disallowType }) {
19
+ this.opts = { file, allowType, disallowType };
20
+ this.file = file;
21
+ }
22
+
23
+ async init() {
24
+ const allowed = Util.isAllowedType(this.opts);
25
+ if (!allowed) return;
26
+ if (!this.file.src.includes('data-escape')) return;
27
+
28
+ const pattern = /(<code-block\b[^>]*\bdata-escape\b[^>]*>)([\s\S]*?)(<\/code-block>)/gi;
29
+
30
+ this.file.src = this.file.src.replace(pattern, (match, openTag, content, closeTag) => {
31
+ const cleanedTag = openTag.replace(/\s*\bdata-escape\b/, '');
32
+ const trimmed = content.replace(/^\n+/, '').replace(/\n+$/, '');
33
+ const escaped = this.escapeHtml(trimmed);
34
+ const encoded = Buffer.from(escaped).toString('base64');
35
+ const tagWithAttr = cleanedTag.replace(/>$/, ` data-cook-esc="${encoded}">`);
36
+ return `${tagWithAttr}${closeTag}`;
37
+ });
38
+ }
39
+
40
+ escapeHtml(str) {
41
+ return str
42
+ .replace(/&/g, '&amp;')
43
+ .replace(/</g, '&lt;')
44
+ .replace(/>/g, '&gt;')
45
+ .replace(/"/g, '&quot;')
46
+ .replace(/'/g, '&#39;');
47
+ }
48
+
49
+ static async export(opts) {
50
+ return new EscapeCodeBlocks(opts).init();
51
+ }
52
+ }
53
+
54
+ export default EscapeCodeBlocks.export;