umberto 7.0.2 → 8.0.1

package/src/tasks/build-documentation.js

@@ -28,7 +28,7 @@ const copyProjectIcons = require( './copy-project-icons' );
 const executeHooks = require( './execute-hooks' );
 const umbertoVersion = require( '../../package.json' ).version;
 
-const parseLink = require( '../../scripts/utils/parselinks' );
+const { parseLinks } = require( '../../scripts/utils/parselinks' );
 const getFilePatternsToProcess = require( '../helpers/get-file-patterns-to-process' );
 
 /**
@@ -141,6 +141,8 @@ module.exports = options => {
 				googleoptimize: mainConfig.googleoptimize,
 				googletagmanager: mainConfig.googletagmanager,
 				googleanalytics: mainConfig.googleanalytics,
+				promobar: mainConfig.promobar,
+				sitemap: mainConfig.sitemap,
 				vwo: mainConfig.vwo,
 				feedbackWidget: mainConfig.feedbackWidget,
 				extraStyles,
@@ -149,11 +151,19 @@ module.exports = options => {
 				additionalDocumentation: mainConfig.additionalDocumentation,
 				canonicalUrlBeginning: mainConfig.canonicalUrlBeginning,
 				macrosVariables: mainConfig.variables,
+				quickNavigationProjects: mainConfig.quickNavigationProjects || [
+					{ name: 'CKEditor 5', slug: 'ckeditor5' },
+					{ name: 'Cloud Services', slug: 'cs' },
+					{ name: 'CKBox', slug: 'ckbox' }
+				],
 				guides,
 				skipGuides
 			} );
 		} )
-		.then( () => hexoManager.generate( { watch } ) )
+		.then( () => hexoManager.generate( {
+			watch,
+			concurrency: 80
+		} ) )
 		.then( () => buildSnippets( hexoManager.hexo.projectGlobals ) )
 		.then( () => copyProjectIcons( hexoManager.hexo.projectGlobals, hexoManager.getPublicDir() ) )
 		// A workaround for API guides when API generation is skipped.
@@ -252,7 +262,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 
 	// If the `guides` (non-empty array) or `skipGuides` options are specified, disable the `{@link...}` validator.
 	if ( options.guides.length || options.skipGuides ) {
-		hexoManager.hexo.projectGlobals.common._disabledFilters.add( parseLink.name );
+		hexoManager.hexo.projectGlobals.common._disabledFilters.add( parseLinks.name );
 	}
 
 	if ( !options.skipApi ) {
@@ -265,11 +275,14 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 				googleoptimize: options.googleoptimize,
 				googletagmanager: options.googletagmanager,
 				googleanalytics: options.googleanalytics,
+				promobar: options.promobar,
+				sitemap: options.sitemap,
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,
 				og: options.og,
 				canonicalUrlBeginning: options.canonicalUrlBeginning,
-				macrosVariables: options.macrosVariables
+				macrosVariables: options.macrosVariables,
+				quickNavigationProjects: options.quickNavigationProjects
 			} )
 		);
 	}
@@ -284,11 +297,14 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			googleoptimize: options.googleoptimize,
 			googletagmanager: options.googletagmanager,
 			googleanalytics: options.googleanalytics,
+			promobar: options.promobar,
+			sitemap: options.sitemap,
 			vwo: options.vwo,
 			feedbackWidget: options.feedbackWidget,
 			og: options.og,
 			canonicalUrlBeginning: options.canonicalUrlBeginning,
-			macrosVariables: options.macrosVariables
+			macrosVariables: options.macrosVariables,
+			quickNavigationProjects: options.quickNavigationProjects
 		} ) );
 	}
 
@@ -337,6 +353,8 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			googleoptimize: options.googleoptimize,
 			googletagmanager: options.googletagmanager,
 			googleanalytics: options.googleanalytics,
+			promobar: options.promobar,
+			quickNavigationProjects: options.quickNavigationProjects,
 			vwo: options.vwo,
 			feedbackWidget: options.feedbackWidget,
 			extraStylePaths: extraStyles,
@@ -390,15 +408,16 @@ async function getProjectConfigs( rootPath, projectPaths, options = {} ) {
 }
 
 // Renders API docs HTML. API docs are rendered separate from hexo so hexo filters and helpers are not available.
-function buildApis( projectConfigs, options = {} ) {
+async function buildApis( projectConfigs, options = {} ) {
 	// Basic project info like name and BASE_PATH required by templates.
 	const basicProjectsData = getBasicProjectsData( projectConfigs );
 	const promises = [];
+	const outputDir = upath.relative( process.cwd(), hexoManager.getPublicDir() );
 
-	projectConfigs.forEach( config => {
+	for ( const config of projectConfigs ) {
 		// If umberto.json doesn't have a config for API docs, we can skip here.
 		if ( !config.groups || !config.groups.find( group => group.id === 'api-reference' ) ) {
-			return;
+			continue;
 		}
 
 		const apiConfig = config.groups.find( group => group.id === 'api-reference' );
@@ -418,18 +437,20 @@ function buildApis( projectConfigs, options = {} ) {
 			throw new Error( `Not enough api-reference data in umberto.json, project: ${ config.name }` );
 		}
 
-		const apiDocs = buildApi( {
+		const apiDocsPromise = buildApi( {
 			src: upath.join( config.projectRootPath, config.path, apiConfig.sourceDir ),
 			projectDst: upath.join( BASE_PATH, apiConfig.slug ),
-			outputDir: hexoManager.getPublicDir().replace( process.cwd(), '' ),
+			outputDir,
 			themePath: hexoManager.getThemePath(),
 			BASE_PATH,
 			docSearch: options.docSearch,
 			macrosVariables: options.macrosVariables,
 			templateLocals: {
 				projectsData: basicProjectsData,
+				quickNavigationProjects: options.quickNavigationProjects,
 				extraStylePaths: options.extraStyles,
 				extraScriptsPaths: options.extraScripts,
+				sitemap: config.sitemap || options.sitemap,
 				umbertoVersion,
 				projectLocals: {
 					extraStylePaths: extraStyles,
@@ -444,25 +465,33 @@ function buildApis( projectConfigs, options = {} ) {
 				googleoptimize: options.googleoptimize,
 				googletagmanager: options.googletagmanager,
 				googleanalytics: options.googleanalytics,
+				promobar: options.promobar,
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,
 				pathJoin: upath.join,
-				mainOg: options.og || {}
+				mainOg: options.og || {},
+				isLegacy: false,
+				isNightly: options.docSearch?.indexName?.includes( 'nightly' ) || false
 			},
 			projectConfig: config,
 			canonicalUrlBeginning: getCanonicalBeginning( { config, options, hexoManager } )
+		} ).then( apiDocs => {
+			// API docs navigation tree is rendered once and reused as HTML.
+			config.navTree = apiDocs.getNavTree();
+			// API errors documentation is stored here so that it's available in guides (and hexo filters).
+			config.errorsHtml = apiDocs.getErrors();
+			hexoManager.addProjectGlobalData( config.slug, 'doclets', apiDocs.getDataCollection() );
+
+			bindProjectGlobals( hexoManager.hexo, {
+				rootPath: config.projectRootPath,
+				basePath: BASE_PATH,
+				config,
+				errorsHtml: config.errorsHtml
+			} );
 		} );
 
-		promises.push(
-			writeHtmlFiles( apiDocs.getFiles() )
-		);
-
-		// API docs navigation tree is rendered once and reused as HTML.
-		config.navTree = apiDocs.getNavTree();
-		// API errors documentation is stored here so that it's available in guides (and hexo filters).
-		config.errorsHtml = apiDocs.getErrors();
-		hexoManager.addProjectGlobalData( config.slug, 'doclets', apiDocs.getDataCollection() );
-	} );
+		promises.push( apiDocsPromise );
+	}
 
 	return Promise.all( promises );
 }
@@ -470,6 +499,7 @@ function buildApis( projectConfigs, options = {} ) {
 function buildSdks( projectConfigs, options = {} ) {
 	const promises = [];
 	const basicProjectsData = getBasicProjectsData( projectConfigs );
+	const outputDir = upath.relative( process.cwd(), hexoManager.getPublicDir() );
 
 	projectConfigs.forEach( config => {
 		const sdkGroup = config.groups && config.groups.find( group => group.id === 'sdk' );
@@ -491,7 +521,7 @@ function buildSdks( projectConfigs, options = {} ) {
 		);
 
 		const sdk = buildSdk( {
-			outputDir: hexoManager.getPublicDir().replace( process.cwd(), '' ),
+			outputDir,
 			srcPath: sdkGroup.sourceDir,
 			projectRootPath: config.projectRootPath,
 			projectPath: config.path,
@@ -503,6 +533,7 @@ function buildSdks( projectConfigs, options = {} ) {
 				umbertoVersion,
 				extraStylePaths: options.extraStyles,
 				extraScriptsPaths: options.extraScripts,
+				sitemap: config.sitemap || options.sitemap,
 				projectLocals: {
 					disableSearch: config.docsearch === false,
 					extraStylePaths: extraStyles,
@@ -513,6 +544,8 @@ function buildSdks( projectConfigs, options = {} ) {
 				googleoptimize: options.googleoptimize,
 				googletagmanager: options.googletagmanager,
 				googleanalytics: options.googleanalytics,
+				quickNavigationProjects: options.quickNavigationProjects,
+				promobar: options.promobar,
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,
 				pathJoin: upath.join,
@@ -529,13 +562,13 @@ function buildSdks( projectConfigs, options = {} ) {
 		// Copy assets
 		copyFiles(
 			upath.join( config.projectRootPath, config.path, sdkGroup.sourceDir, 'assets' ),
-			upath.join( '.', hexoManager.getPublicDir().replace( process.cwd(), '' ), BASE_PATH, sdkGroup.slug, 'assets' )
+			upath.join( '.', outputDir, BASE_PATH, sdkGroup.slug, 'assets' )
 		);
 
 		// Copy CKEditor from presets
 		copyFiles(
 			upath.join( config.projectRootPath, config.path, sdkGroup.sourceDir, 'vendors' ),
-			upath.join( '.', hexoManager.getPublicDir().replace( process.cwd(), '' ), 'vendors', config.version )
+			upath.join( '.', outputDir, 'vendors', config.version )
 		);
 
 		config.sdkNavTree = sdk.navigationHtml;

package/src/tasks/cache-files.js

@@ -27,7 +27,7 @@ module.exports = ( src, dst ) => {
 		if ( !fs.existsSync( cachePath ) ) {
 			try {
 				fs.copySync( p, cachePath );
-			} catch ( err ) {
+			} catch {
 				console.error( `Error when caching file ${ p } to ${ cachePath }` );
 			}
 
@@ -40,7 +40,7 @@ module.exports = ( src, dst ) => {
 		if ( currentStats.size !== cachedStats.size || currentStats.mtime > cachedStats.mtime ) {
 			try {
 				fs.copySync( p, cachePath );
-			} catch ( err ) {
+			} catch {
 				console.error( `Error when caching file ${ p } to ${ cachePath }` );
 			}
 

package/src/tasks/compile-sass.js

@@ -15,6 +15,18 @@ module.exports = ( src, dst ) => {
 			file: src,
 			outputStyle: 'compressed',
 			importer( url, file, done ) {
+				// In case of import from the `themes/umberto/src` directory.
+				const themeMatch = url && url.match( /@([^/]+)\/(.+)/ );
+
+				if ( themeMatch ) {
+					const [ , theme, remainingPath ] = themeMatch;
+					const filePath = upath.join( __dirname, '../../themes/umberto/src', theme, 'css', remainingPath );
+
+					if ( fs.existsSync( filePath ) ) {
+						return done( { file: filePath } );
+					}
+				}
+
 				// In case of an import from the `node_modules` directory.
 				if ( url.startsWith( '~' ) ) {
 					// Resolve the path regarding the current working directory.

package/src/tasks/copy-assets.js

@@ -17,6 +17,10 @@ const copyFiles = require( './copy-files' );
  */
 module.exports = ( themeDir, outputPath ) => {
 	return Promise.all( [
+		copyFiles(
+			upath.join( themeDir, 'assets', '_fonts' ),
+			upath.join( outputPath, 'fonts' )
+		),
 		copyFiles(
 			upath.join( themeDir, 'assets', '_img' ),
 			upath.join( outputPath, 'img' )

package/src/tasks/copy-project-icons.js

@@ -24,7 +24,7 @@ module.exports = async function copyProjectIcons( projectGlobals, buildDirectory
 
 			try {
 				await fs.copy( fullSourcePath, fullDestinationPath );
-			} catch ( error ) {
+			} catch {
 				console.warn(
 					`⚠️ The "${ sourceFile }" icon cannot be copied because it does not exist in "${ fullSourcePath }".`
 				);

package/src/tasks/get-extra-files.js

@@ -25,7 +25,7 @@ module.exports = ( rootPath, dst, files ) => {
 				fs.accessSync( resolvedPath );
 
 				return true;
-			} catch ( err ) {
+			} catch {
 				console.error( `Extra file not found in ${ resolvedPath }` );
 
 				return false;

package/src/tasks/get-project-config.js

@@ -328,7 +328,7 @@ function getRepositoryUrl( rootPath ) {
 function getPackageJson( rootPath ) {
 	try {
 		return require( upath.join( rootPath, 'package.json' ) );
-	} catch ( err ) {
+	} catch {
 		return null;
 	}
 }

package/src/tasks/overwrite-api-guides.js

@@ -33,7 +33,7 @@ module.exports = ( src, dst ) => {
 		if ( currentStats.size !== cachedStats.size ) {
 			try {
 				fs.copySync( p, destinationPath );
-			} catch ( err ) {
+			} catch {
 				console.error( `Error when copying file ${ p } to ${ destinationPath }` );
 			}
 		}

package/src/tasks/validate-links.js

@@ -5,42 +5,51 @@
 
 'use strict';
 
+/**
+ * Script for validating links in generated HTML files.
+ * Uses multiple threads (worker_threads) for parallel analysis, significantly speeding up the build process,
+ * especially for API documentation where the number of links can reach thousands.
+ */
+
 const { styleText } = require( 'util' );
 const upath = require( 'upath' );
 const fs = require( 'fs-extra' );
+const os = require( 'os' );
+const { Worker, isMainThread, parentPort, workerData } = require( 'worker_threads' );
 const { globSync } = require( 'glob' );
 const { parseDocument } = require( 'htmlparser2' );
+const { isMaskedID } = require( '../../scripts/utils/random-id' );
 
-module.exports = ( buildPath, options = {} ) => {
-	const pattern = upath.join( buildPath, '**', '*' );
-	let pathsToFiles = globSync( pattern ).map( path => upath.normalize( path ) );
-
+/**
+ * Collects all links from the provided HTML files.
+ * Skips files from the vendors directory and (optionally) api.
+ * Adds links to files and their fragments (#id).
+ *
+ * @param {string[]} pathsToFiles Array of file paths to process.
+ * @param {Object} options Options for filtering files.
+ * @returns {{links: Set<string>, pathsToFiles: string[]}}
+ */
+function collectLinks( pathsToFiles, options ) {
 	const links = new Set();
-
 	pathsToFiles = pathsToFiles.filter( p => {
 		if ( p.includes( '/vendors/' ) ) {
 			return false;
 		}
 
-		if ( options.skipApi && ( p.includes( '/api/' ) ) ) {
+		if ( options.skipApi && p.includes( '/api/' ) ) {
 			return false;
 		}
 
 		if ( !p.endsWith( '.html' ) ) {
-			// Add assets like .png, .xlsx, .docx as valid links.
 			const resolvePath = upath.resolve( p );
-
 			if ( fs.statSync( resolvePath ).isFile() ) {
 				links.add( upath.resolve( resolvePath ) );
 			}
-
 			return false;
 		}
-
 		return true;
 	} );
 
-	// Obtain every possible hash
 	for ( const filePath of pathsToFiles ) {
 		links.add( upath.resolve( filePath ) );
 		links.add( upath.resolve( filePath + '#' ) );
@@ -49,27 +58,40 @@ module.exports = ( buildPath, options = {} ) => {
 		const ids = ( content.match( /id="[^"]+"/g ) || [] ).map( el => el.replace( /^id="/, '' ).replace( /"$/, '' ) );
 
 		for ( const id of ids ) {
-			links.add( upath.resolve( `${ filePath }#${ id }` ) );
+			if ( !isMaskedID( id ) && !ids.includes( 'icons-' ) ) {
+				links.add( upath.resolve( `${ filePath }#${ id }` ) );
+			}
 		}
 	}
 
-	// Check if links are in set of possible hashes.
-	for ( const filePath of pathsToFiles ) {
-		const invalidHrefs = new Set();
+	return {
+		links: Array.from( links ),
+		pathsToFiles
+	};
+}
+
+/**
+ * Validates links in the given chunk of files.
+ * Checks if links point to existing files or fragments.
+ * Returns a list of invalid links.
+ *
+ * @param {Object} params
+ * @param {string[]} params.chunk Array of file paths to validate.
+ * @param {Set<string>} params.links Set of valid links.
+ * @param {Object} params.options Validation options.
+ * @returns {Array<Object>}
+ */
+function validateChunk( { chunk, links, options } ) {
+	const errors = [];
+
+	for ( const filePath of chunk ) {
+		const invalidHrefs = [];
 		const content = fs.readFileSync( filePath, 'utf-8' );
 		const linkElements = [];
 
 		processNode( parseDocument( content ), linkElements );
 
-		for ( let { href, text, skipValidation } of linkElements ) {
-			if (
-				href.match( /[a-z:]*\/\// ) ||
-				href.match( /mailto:/ ) ||
-				skipValidation
-			) {
-				continue;
-			}
-
+		for ( let { href, text } of linkElements ) {
 			if ( href.endsWith( '/' ) && !href.includes( '#' ) ) {
 				href += 'index.html';
 			}
@@ -77,8 +99,6 @@ module.exports = ( buildPath, options = {} ) => {
 			let resolvedPath = getResolvedPath( href, filePath, { publicDir: options.publicDir } );
 
 			if ( options.skipApi && resolvedPath.includes( '/api/' ) ) {
-				// Sometimes api url are obtained after resolving entire URL.
-
 				continue;
 			}
 
@@ -87,7 +107,6 @@ module.exports = ( buildPath, options = {} ) => {
 					options.projectsInfo.find( i => resolvedPath.includes( `/${ i.slug }/` ) ) :
 					null;
 				const projectVersion = projectInfo ? projectInfo.version : 'latest';
-
 				resolvedPath = resolvedPath.replace( 'latest', projectVersion );
 			}
 
@@ -100,32 +119,140 @@ module.exports = ( buildPath, options = {} ) => {
 					continue;
 				}
 			}
-
 			if ( !links.has( resolvedPath ) ) {
-				invalidHrefs.add( { href, text } );
+				invalidHrefs.push( { href, text, filePath } );
 			}
 		}
 
-		if ( invalidHrefs.size ) {
-			process.exitCode = 1;
+		if ( invalidHrefs.length ) {
+			errors.push( { filePath, invalidHrefs } );
+		}
+	}
+
+	return errors;
+}
+
+/**
+ * Main function executed in the main thread.
+ * Splits files into chunks and runs worker threads for each chunk.
+ * Collects results and prints errors.
+ *
+ * @param {string} buildPath Path to the build directory.
+ * @param {Object} [options={}] Validation options.
+ */
+if ( isMainThread ) {
+	const validateLinks = ( buildPath, options = {} ) => {
+		const pattern = upath.join( buildPath, '**', '*' );
+		const pathsToFiles = globSync( pattern ).map( path => upath.normalize( path ) );
+
+		console.info( `Validating links in ${ styleText( 'magenta', buildPath ) }...` );
+
+		const start = Date.now();
+		const { links, pathsToFiles: filteredPaths } = collectLinks( pathsToFiles, options );
+
+		const cpuCount = Math.max( 1, os.cpus().length );
+		const maxWorkers = 8;
+		const workerCount = Math.min( cpuCount, maxWorkers );
+		const chunks = chunkBasedOnMemory( workerCount, filteredPaths );
+
+		let finished = 0;
+		let allErrors = [];
+		let nextChunkIdx = 0;
+		const totalChunks = chunks.length;
+
+		return new Promise( ( resolve, reject ) => {
+			const workers = [];
+
+			function startWorker( workerId ) {
+				if ( nextChunkIdx >= totalChunks ) {
+					return;
+				}
+				const chunkIdx = nextChunkIdx++;
+				const worker = new Worker( __filename, {
+					workerData: {
+						chunk: chunks[ chunkIdx ],
+						links,
+						buildPath,
+						options
+					}
+				} );
+
+				worker.on( 'message', errors => {
+					allErrors = allErrors.concat( errors );
+					finished++;
+					console.info( `Processed ${ finished } of ${ totalChunks } links chunks.` );
+
+					if ( nextChunkIdx < totalChunks ) {
+						startWorker( workerId ); // Start next chunk on this worker
+					} else if ( finished === totalChunks ) {
+						printErrors( allErrors, buildPath );
+						console.info( `Links validation finished in ${ styleText( 'green', ( Date.now() - start ) + 'ms' ) }.` );
+
+						if ( allErrors.length ) {
+							reject( new Error( `Found ${ allErrors.length } invalid links.` ) );
+						} else {
+							resolve();
+						}
+					}
+				} );
+
+				worker.on( 'error', err => {
+					finished++;
+					console.error( styleText( 'red', `Worker error: ${ err }` ) );
+					if ( nextChunkIdx < totalChunks ) {
+						startWorker( workerId );
+					} else if ( finished === totalChunks ) {
+						reject( new Error( `Worker error: ${ err }` ) );
+					}
+				} );
+				workers[ workerId ] = worker;
+			}
+
+			const numWorkers = Math.min( workerCount, totalChunks );
+			for ( let i = 0; i < numWorkers; i++ ) {
+				startWorker( i );
+			}
+		} );
+	};
+
+	module.exports = validateLinks;
+} else {
+	const { chunk, links, options } = workerData;
+	const errors = validateChunk( { chunk, links: new Set( links ), options } );
+
+	parentPort.postMessage( errors );
+}
+
+/**
+ * Prints errors found during link validation.
+ * Sets exit code to 1 if errors occurred.
+ *
+ * @param {Array<Object>} allErrors
+ * @param {string} buildPath
+ */
+function printErrors( allErrors, buildPath ) {
+	if ( allErrors.length ) {
+		process.exitCode = 1;
+		for ( const { filePath, invalidHrefs } of allErrors ) {
 			console.log(
 				styleText( 'red', 'Error: ' ) +
 				`Invalid internal links in ${ styleText( 'magenta', filePath.replace( buildPath, '' ) ) }:`
 			);
-
 			for ( const url of invalidHrefs ) {
 				console.log( styleText( 'gray', `  * '${ url.href }' - ${ url.text.replace( /\s+/g, ' ' ) }` ) );
 			}
 		}
 	}
-};
+}
 
 /**
- * @param {String} href A relative or absolute URL to the page.
- * @param {String} filePath A relative path (to the options.publicDir) to the checked file.
+ * Resolves the target path for the given href relative to the file and public directory.
+ *
+ * @param {string} href
+ * @param {string} filePath
  * @param {Object} options
- * @param {String} options.publicDir An absolute path to the directory where all files are located.
- * @return {string}
+ * @param {string} options.publicDir
+ * @returns {string}
  */
 function getResolvedPath( href, filePath, options ) {
 	if ( href.startsWith( '#' ) ) {
@@ -146,14 +273,20 @@ function getResolvedPath( href, filePath, options ) {
 	return upath.resolve( filePath, '..', href );
 }
 
+/**
+ * Recursively processes the DOM tree, collecting <a> elements with href.
+ *
+ * @param {Object} node
+ * @param {Array<Object>} linkElements
+ */
 function processNode( node, linkElements ) {
 	if ( node.type === 'tag' && node.name === 'a' ) {
 		const text = node.children.find( child => child.type === 'text' )?.data;
 		const href = node.attribs?.href;
 		const skipValidation = node.attribs?.[ 'data-skip-validation' ] !== undefined;
 
-		if ( text && href ) {
-			linkElements.push( { href, text, skipValidation } );
+		if ( !skipValidation && text && href && !href.match( /[a-z:]*\/\// ) && !href.match( /mailto:/ ) ) {
+			linkElements.push( { href, text } );
 		}
 	}
 
@@ -165,3 +298,42 @@ function processNode( node, linkElements ) {
 		processNode( childNode, linkElements );
 	}
 }
+
+/**
+ * Calculates the optimal chunk count for splitting files based on available system memory.
+ * Tries to keep each chunk small enough to avoid OOM, but not too small for efficiency.
+ */
+function chunkBasedOnMemory( maxWorkers, array ) {
+	const totalMem = os.totalmem();
+	const freeMem = os.freemem();
+
+	// Assume each file may take up to 8MB in memory (parsing, DOM, etc.)
+	const perFileEstimate = 8 * 1024 * 1024;
+
+	// Use only a portion of free memory to be safe (e.g., 60%)
+	const usableMem = Math.max( freeMem, totalMem * 0.2 ) * 0.6;
+	const maxFilesPerChunk = Math.max( 1, Math.floor( usableMem / perFileEstimate ) );
+
+	// Try to keep chunks small, but not less than maxWorkers
+	const chunkCount = Math.max( maxWorkers, Math.ceil( array.length / maxFilesPerChunk ) );
+
+	return chunkArray( array, chunkCount );
+}
+
+/**
+ * Splits an array into chunkCount fragments of similar size.
+ *
+ * @param {Array} array
+ * @param {number} chunkCount
+ * @returns {Array<Array>}
+ */
+function chunkArray( array, chunkCount ) {
+	const chunks = [];
+	const chunkSize = Math.ceil( array.length / chunkCount );
+
+	for ( let i = 0; i < array.length; i += chunkSize ) {
+		chunks.push( array.slice( i, i + chunkSize ) );
+	}
+
+	return chunks;
+}