umberto 8.3.4 → 8.4.0

package/CHANGELOG.md

@@ -1,46 +1,49 @@
 Changelog
 =========
 
-## [8.3.4](https://github.com/cksource/umberto/compare/v8.3.3...v8.3.4) (October 20, 2025)
+## [8.4.0](https://github.com/cksource/umberto/compare/v8.3.5...v8.4.0) (October 30, 2025)
 
-### Other changes
+### Features
 
-* Bump dependencies (including `hexo` to version `8.0.0`).
+* Minify output HTML to reduce file size and improve load performance.
 
+  The output is automatically minified during production builds to remove unnecessary whitespace and comments.
 
-## [8.3.3](https://github.com/cksource/umberto/compare/v8.3.2...v8.3.3) (October 15, 2025)
+  Minification is **disabled when using the `--dev` modifier**, ensuring the generated HTML remains readable for easier debugging and inspection.
 
-### Bug fixes
+### Other changes
 
-* Link validator should not fail on links containing the word "latest", if they are not part of a version number.
-* Fixed links being unstyled in Kapa.ai answers.
-* Fix broken page sidebar layout on `959px` resolution.
+* Umberto reads a project configuration once and passes it through the pipeline. Thanks to that, hooks can modify it, which affects a project's build.
 
 
-## [8.3.2](https://github.com/cksource/umberto/compare/v8.3.1...v8.3.2) (September 16, 2025)
+## [8.3.5](https://github.com/cksource/umberto/compare/v8.3.4...v8.3.5) (October 29, 2025)
 
 ### Other changes
 
-* Update to TypeScript 5.3.
+* Hook scripts now receive the full project configuration object when executed.
 
 
-## [8.3.1](https://github.com/cksource/umberto/compare/v8.3.0...v8.3.1) (September 4, 2025)
+## [8.3.4](https://github.com/cksource/umberto/compare/v8.3.3...v8.3.4) (October 20, 2025)
 
-### Bug fixes
+### Other changes
+
+* Bump dependencies (including `hexo` to version `8.0.0`).
 
-* Fixed link styles not being applied to followup questions in `Kapa.ai` integration.
 
-### Other changes
+## [8.3.3](https://github.com/cksource/umberto/compare/v8.3.2...v8.3.3) (October 15, 2025)
+
+### Bug fixes
 
-* Increased size of the modal in `Kapa.ai` integration.
+* Link validator should not fail on links containing the word "latest", if they are not part of a version number.
+* Fixed links being unstyled in Kapa.ai answers.
+* Fix broken page sidebar layout on `959px` resolution.
 
 
-## [8.3.0](https://github.com/cksource/umberto/compare/v8.2.0...v8.3.0) (September 2, 2025)
+## [8.3.2](https://github.com/cksource/umberto/compare/v8.3.1...v8.3.2) (September 16, 2025)
 
-### Features
+### Other changes
 
-* Added custom styling for the [Kapa.ai](https://www.kapa.ai/) service.
-* The source script of the [Kapa.ai](https://www.kapa.ai/) service must be defined in the `kapa.widgetOptions.src` key in the Umberto configuration.
+* Update to TypeScript 5.3.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "8.3.4",
+  "version": "8.4.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -17,6 +17,7 @@
     "@babel/core": "^7.18.10",
     "@babel/preset-env": "^7.18.10",
     "@ckeditor/jsdoc-plugins": "^43.0.0",
+    "@minify-html/node": "^0.17.1",
     "babel-loader": "^10.0.0",
     "cheerio": "^1.0.0",
     "escape-string-regexp": "^4.0.0",
@@ -28,8 +29,8 @@
     "hexo-generator-category": "^2.0.0",
     "hexo-generator-index": "^4.0.0",
     "hexo-generator-tag": "^2.0.0",
-    "hexo-renderer-pug": "^3.0.0",
     "hexo-renderer-markdown-it-plus": "^1.0.5",
+    "hexo-renderer-pug": "^3.0.0",
     "htmlparser2": "^10.0.0",
     "javascript-stringify": "^2.1.0",
     "jquery": "~3.7.1",
@@ -46,6 +47,7 @@
     "sass": "^1.54.0",
     "shiki": "^3.4.0",
     "sitemap": "^8.0.0",
+    "tinypool": "^2.0.0",
     "tippy.js": "^6.3.7",
     "tree-model": "^1.0.7",
     "upath": "^2.0.1",
@@ -71,6 +73,6 @@
     ]
   },
   "hexo": {
-    "version": "7.3.0"
+    "version": "8.0.0"
   }
 }

package/src/tasks/build-documentation.js

@@ -26,6 +26,7 @@ const createSitemapStep = require( './create-sitemap-step' );
 const buildSnippets = require( './build-snippets' );
 const copyProjectIcons = require( './copy-project-icons' );
 const executeHooks = require( './execute-hooks' );
+const minifyHtml = require( './minify-html' );
 const umbertoVersion = require( '../../package.json' ).version;
 
 const { parseLinks } = require( '../../scripts/utils/parselinks' );
@@ -49,6 +50,7 @@ const getFilePatternsToProcess = require( '../helpers/get-file-patterns-to-proce
  * clean option can be used to clear the build directory or not.
  * @param {Boolean} options.dev If true, it indicates a local build, skips minification, reuses already built files, allows to skip webpack.
  * @param {Boolean} options.skipApi Skip rendering API docs.
+ * @param {Boolean} options.skipSdk Skip building SDK docs.
  * @param {Boolean} options.skipLiveSnippets Skip building live code snippets.
  * @param {Array.<String>|String} options.extraStyles Path/s to extra css.
  * @param {Array.<String>|String} options.extraScripts Path/s to extra js.
@@ -69,6 +71,7 @@ module.exports = options => {
 		clean = !options.dev,
 		dev = false,
 		skipApi = false,
+		skipSdk = false,
 		skipLiveSnippets = false,
 		extraStyles = [],
 		extraScripts = [],
@@ -127,13 +130,14 @@ module.exports = options => {
 			} );
 		} )
 		.then( async () => {
-			const configs = await getProjectConfigs( rootPath, projectPaths );
+			const configs = await getProjectConfigs( rootPath, projectPaths, { skipLiveSnippets } );
 
 			return executeHooks( configs, 'beforeHexo' );
 		} )
 		.then( () => {
 			return buildProjects( rootPath, projectPaths, {
 				skipApi,
+				skipSdk,
 				skipLiveSnippets,
 				dev,
 				docSearch: mainConfig.docsearch,
@@ -205,6 +209,16 @@ module.exports = options => {
 
 			return Promise.resolve();
 		} )
+		// Minify HTML files.
+		.then( async () => {
+			if ( options.dev ) {
+				return Promise.resolve();
+			}
+
+			const outputDir = upath.relative( process.cwd(), hexoManager.getPublicDir() );
+
+			return minifyHtml( outputDir );
+		} )
 		// Links validation.
 		.then( async () => {
 			const projectConfigs = await getProjectConfigs( rootPath, projectPaths, {
@@ -233,12 +247,12 @@ module.exports = options => {
 			} );
 		} )
 		.then( async () => {
-			const projectConfigs = await getProjectConfigs( rootPath, projectPaths );
+			const projectConfigs = await getProjectConfigs( rootPath, projectPaths, { skipLiveSnippets } );
 
 			return createSitemapStep( { projectConfigs, verbose, mainConfig } );
 		} )
 		.then( async () => {
-			const configs = await getProjectConfigs( rootPath, projectPaths );
+			const configs = await getProjectConfigs( rootPath, projectPaths, { skipLiveSnippets } );
 
 			return executeHooks( configs, 'afterHexo' );
 		} )
@@ -396,15 +410,9 @@ async function getProjectConfigs( rootPath, projectPaths, options = {} ) {
 	const promises = projectPaths.map( async pPath => {
 		const projectRootPath = upath.join( rootPath, pPath );
 
-		return Object.assign(
-			{},
-			{
-				...await getProjectConfig( projectRootPath, {
-					skipLiveSnippets: options.skipLiveSnippets
-				} ),
-				projectRootPath
-			}
-		);
+		return getProjectConfig( projectRootPath, {
+			skipLiveSnippets: options.skipLiveSnippets
+		} );
 	} );
 
 	return Promise.all( promises );

package/src/tasks/execute-hooks.js

@@ -34,7 +34,7 @@ module.exports = async function executeHooks( configs, hookName ) {
 			}
 
 			for ( const scriptPath of config.hooks[ hookName ] ) {
-				await processSingleHook( upath.dirname( config.__configPath ), scriptPath );
+				await processSingleHook( config, scriptPath );
 			}
 		}
 
@@ -48,17 +48,18 @@ module.exports = async function executeHooks( configs, hookName ) {
 };
 
 /**
- * @param {String} configPath
+ * @param {Object} config
  * @param {String} scriptPath
  * @return {Promise}
  */
-async function processSingleHook( configPath, scriptPath ) {
+async function processSingleHook( config, scriptPath ) {
+	const configPath = upath.dirname( config.__configPath );
 	const callbackAbsolutePath = upath.join( configPath, scriptPath );
 
 	try {
 		const callback = await importModule( callbackAbsolutePath );
 
-		await callback();
+		await callback( config );
 	} catch ( error ) {
 		// Store a path to the executed file.
 		error._filePath = scriptPath;

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

@@ -32,6 +32,7 @@ module.exports = async ( rootPath, options = {} ) => {
 
 	const config = getConfigurationFile( configPath );
 
+	config.projectRootPath = rootPath;
 	config.__configPath = configPath;
 
 	// Get the `realImportPath()` function. It displays an import path of a class below the class title.

package/src/tasks/minify-html.js

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { join } = require( 'path' );
+const { globSync } = require( 'fs' );
+const { styleText } = require( 'util' );
+const { default: TinyPool } = require( 'tinypool' );
+
+/**
+ * Minifies all HTML files under outputDir in parallel using tinypool.
+ *
+ * @param {string} outputDir - base directory to search for *.html files
+ */
+module.exports = async function minifyHtml( outputDir ) {
+	const files = globSync( join( outputDir, '**', 'api', '**', '*.html' ) );
+
+	const pool = new TinyPool( {
+		runtime: 'child_process',
+		filename: require.resolve( './minify-worker.js' )
+	} );
+
+	try {
+		console.log( 'Started HTML minification.' );
+
+		const results = await Promise.allSettled(
+			files.map( async file => {
+				try {
+					return await pool.run( file );
+				} catch ( err ) {
+					err.file = file;
+					throw err;
+				}
+			} )
+		);
+
+		const failed = results.filter( r => r.status === 'rejected' );
+
+		if ( failed.length > 0 ) {
+			failed.forEach( ( { reason } ) => {
+				console.error( styleText( 'redBright', `Minification failed for "${ reason.file }": ${ reason.message }` ) );
+			} );
+
+			throw new Error( `Minification failed for ${ failed.length } file(s).` );
+		}
+	} finally {
+		await pool.destroy();
+
+		console.log( 'Finished HTML minification.' );
+	}
+};

package/src/tasks/minify-worker.js

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { readFileSync, writeFileSync } = require( 'fs' );
+const minifier = require( '@minify-html/node' );
+
+/**
+ * Minifies HTML content.
+ *
+ * @param {string} file - Path to the HTML file to minify.
+ * @returns {void}
+ */
+module.exports = function( file ) {
+	const html = readFileSync( file );
+
+	const minified = minifier.minify( html, {
+		keep_comments: true,
+		minify_css: true,
+		minify_js: true
+	} );
+
+	writeFileSync( file, minified );
+};

package/src/tasks/validate-links.js

@@ -55,7 +55,11 @@ function collectLinks( pathsToFiles, options ) {
 		links.add( upath.resolve( filePath + '#' ) );
 
 		const content = fs.readFileSync( filePath, 'utf-8' );
-		const ids = ( content.match( /id="[^"]+"/g ) || [] ).map( el => el.replace( /^id="/, '' ).replace( /"$/, '' ) );
+		// Extract both quoted and unquoted "id" attributes.
+		const ids = [
+			...Array.from( content.matchAll( /id="([^"]+)"/g ), m => m[ 1 ] ),
+			...Array.from( content.matchAll( /id=([^\s"'/>]+)/g ), m => m[ 1 ] )
+		];
 
 		for ( const id of ids ) {
 			if ( !isMaskedID( id ) && !ids.includes( 'icons-' ) ) {

package/themes/umberto/layout/gloria/_modules/header/index.pug

@@ -12,7 +12,7 @@ mixin header({ withChooseProject = true, className = '' } = {})
 		.c-header__mobile.l-hide-desktop
 			.c-header__mobile-brand
 				a.b-link.u-display-inline-flex(
-					title='Go to CKEditor Ecosystem Documentation home page',
+					title='Navigate to the CKEditor Ecosystem Documentation homepage',
 					href=relative_url(page.path, 'index.html')
 				)
 					+inline-svg({ file: 'ckeditor-logo', ariaHidden: true, className: 'c-header__brand-logo' })
@@ -39,7 +39,7 @@ mixin header({ withChooseProject = true, className = '' } = {})
 			.c-header__brand-row
 				.c-header__brand-row-selector.u-flex-horizontal.u-align-items-center
 					a.b-link.u-display-inline-flex(
-						title='Go to CKEditor Ecosystem Documentation home page',
+						title='Navigate to the CKEditor Ecosystem Documentation homepage',
 						href=relative_url(page.path, 'index.html')
 					)
 						+inline-svg({ file: 'ckeditor-logo', ariaHidden: true, className: 'c-header__brand-logo' })

package/themes/umberto/src/gloria/css/base/_tables.scss

@@ -32,7 +32,7 @@
 			text-align: left;
 			font-weight: var(--font-weight-bold);
 			font-family: var(--font-family-heading);
-			background-color: var(--color-gray-200);
+			background-color: var(--color-gray-300);
 		}
 
 		&-wrapper {
@@ -53,7 +53,8 @@
 			@extend .b-table__row;
 		}
 
-		td, th {
+		td,
+		th {
 			@extend .b-table__cell;
 		}
 
@@ -61,4 +62,4 @@
 			@extend .b-table__header;
 		}
 	}
-}
+}

package/themes/umberto/src/gloria/js/components/hash-link.js

@@ -22,7 +22,7 @@ export class HashLink extends BaseComponent {
 		document.addEventListener( 'click', event => {
 			const target = event.target.closest( 'a[href^="#"]' );
 
-			if ( !target ) {
+			if ( !target || event.defaultPrevented ) {
 				return;
 			}