umberto 8.0.2 → 8.1.0

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 Changelog
 =========
 
+## [8.1.0](https://github.com/cksource/umberto/compare/v8.0.3...v8.1.0) (August 12, 2025)
+
+### Features
+
+* Added support for relative paths in `packagesDir` option.
+
+### Bug fixes
+
+* Updated how `<iframe>` elements are created to fix issues with automated tests using Chrome v139.
+
+
+## [8.0.3](https://github.com/cksource/umberto/compare/v8.0.2...v8.0.3) (August 5, 2025)
+
+### Bug fixes
+
+* The backticks in the XML components parser were not escaped correctly, causing issues with parsing XML content. This fix ensures that backticks are properly escaped, allowing the parser to handle XML content containing backticks without errors.
+
+
 ## [8.0.2](https://github.com/cksource/umberto/compare/v8.0.1...v8.0.2) (July 31, 2025)
 
 ### Bug fixes
@@ -47,22 +65,6 @@ Changelog
 * The repository now uses ESLint v9. Therefore, the required Node.js version has been upgraded to 22 to match the ESLint requirements.
 * Update `LICENSE.md` file to include licenses of direct dependencies
 
-
-## [7.0.2](https://github.com/cksource/umberto/compare/v7.0.1...v7.0.2) (2025-05-20)
-
-### Bug fixes
-
-* Fixed an invalid protocol (should be `https://` instead of `https:/`) in the generated index sitemap file. Closes [#1277](https://github.com/cksource/umberto/issues/1277). ([commit](https://github.com/cksource/umberto/commit/6f59654e85b1230fbfe029efe68f708755ec6342))
-
-
-## [7.0.1](https://github.com/cksource/umberto/compare/v7.0.0...v7.0.1) (2025-05-14)
-
-### Other changes
-
-* Updated the project dependencies. Closes [#1253](https://github.com/cksource/umberto/issues/1253). ([commit](https://github.com/cksource/umberto/commit/28d74364207ab055ad76c2857d58cccb1866559b))
-* Removed dependencies that can be replaced with native APIs or other already used dependencies. ([commit](https://github.com/cksource/umberto/commit/28d74364207ab055ad76c2857d58cccb1866559b))
-* Sitemaps will be generated separately for each project. Closes [#1254](https://github.com/cksource/umberto/issues/1254). ([commit](https://github.com/cksource/umberto/commit/7968755b2a4b1c23768a9420292eb1d168b898b3))
-
 ---
 
 To see all releases, visit the [release page](https://github.com/cksource/umberto/releases).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "8.0.2",
+  "version": "8.1.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [

package/scripts/filter/after-post-render/gloria/apply-design-doc-classes.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const applyDesignDocClasses = require( '../../../utils/apply-design-doc-classes' );
 
 /**
  * Global mapping of HTML elements to their corresponding design system classes.
@@ -86,60 +86,11 @@ hexo.extend.filter.register( 'after_post_render', page => {
 		return page;
 	}
 
-	const $ = cheerio.load( page.content, null, false );
-
-	// Apply classes based on the global mapping
-	for ( const [ element, classesOrCallback ] of Object.entries( ELEMENTS_CLASSES_MAPPINGS ) ) {
-		const $elements = $( element );
-
-		$elements.each( ( _, element ) => {
-			const $element = $( element );
-
-			if ( hasClassOrParentWithClass( $element, 'no-transform' ) ) {
-				return;
-			}
-
-			// Add the 'doc' class to each element that gets styled
-			$element.addClass( 'doc' );
-
-			const classList = ( $element.attr( 'class' )?.split( /\s+/ ) || [] ).filter(
-				className => !ELEMENTS_WITH_WHITELIST_CLASSES.includes( className )
-			);
-
-			// Avoid applying classes to elements that already have one.
-			if ( classList.length > 1 ) {
-				return;
-			}
-
-			// Add the specified classes
-			if ( typeof classesOrCallback === 'function' ) {
-				const elementClasses = classesOrCallback( $element );
-
-				if ( Array.isArray( elementClasses ) ) {
-					$element.addClass( elementClasses.join( ' ' ) );
-				} else if ( typeof elementClasses === 'string' ) {
-					$element.addClass( elementClasses );
-				}
-			} else if ( Array.isArray( classesOrCallback ) ) {
-				$element.addClass( classesOrCallback.join( ' ' ) );
-			} else {
-				$element.addClass( classesOrCallback );
-			}
-		} );
-	}
-
-	page.content = $.html();
+	page.content = applyDesignDocClasses( {
+		elementsClassesMappings: ELEMENTS_CLASSES_MAPPINGS,
+		elementsWithWhitelistClasses: ELEMENTS_WITH_WHITELIST_CLASSES,
+		content: page.content
+	} );
 
 	return page;
 }, 40 );
-
-/**
- * Checks if the element itself or any of its parents has the specified class.
- *
- * @param $element - The jQuery element to check.
- * @param className - The class name to look for.
- * @returns True if the element or any parent has the class, false otherwise.
- */
-function hasClassOrParentWithClass( $element, className ) {
-	return $element.hasClass( className ) || $element.parents( `.${ className }` ).length > 0;
-}

package/scripts/filter/after-post-render/gloria/wrap-table-into-wrappers.js

@@ -7,10 +7,7 @@
 
 const cheerio = require( 'cheerio' );
 
-/**
- * Enforce priority 30 to run it after apply design doc classes filter.
- */
-hexo.extend.filter.register( 'after_post_render', page => {
+function wrapTableIntoWrappers( page ) {
 	if ( page.projectTheme !== 'gloria' ) {
 		return page;
 	}
@@ -27,4 +24,13 @@ hexo.extend.filter.register( 'after_post_render', page => {
 	page.content = $.html();
 
 	return page;
-}, 30 );
+};
+
+/**
+ * Enforce priority 30 to run it after apply design doc classes filter.
+ */
+if ( typeof hexo !== 'undefined' ) {
+	hexo.extend.filter.register( 'after_post_render', wrapTableIntoWrappers, 30 );
+}
+
+module.exports = wrapTableIntoWrappers;

package/scripts/utils/apply-design-doc-classes.js

@@ -0,0 +1,82 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const cheerio = require( 'cheerio' );
+
+/**
+ * Add design system classes to the parsed document elements. If element has 0 CSS classes
+ * it'll be considered as not styled and the design system classes will be applied.
+
+ * @param options - Options for applying design classes.
+ * @param options.elementsClassesMappings - Mappings of elements to their classes or
+ *     functions that return classes.
+ * @param options.elementsWithWhitelistClasses - List of classes that are
+ *     considered as transparent in checks for amount of the classes.
+ * @param options.content - The HTML content to process.
+ */
+module.exports = function applyDesignDocClasses(
+	{
+		elementsClassesMappings,
+		elementsWithWhitelistClasses,
+		content
+	}
+) {
+	const $ = cheerio.load( content, null, false );
+
+	// Apply classes based on the global mapping
+	for ( const [ element, classesOrCallback ] of Object.entries( elementsClassesMappings ) ) {
+		const $elements = $( element );
+
+		$elements.each( ( _, element ) => {
+			const $element = $( element );
+
+			if ( hasClassOrParentWithClass( $element, 'no-transform' ) ) {
+				return;
+			}
+
+			// Add the 'doc' class to each element that gets styled
+			$element.addClass( 'doc' );
+
+			const classList = ( $element.attr( 'class' )?.split( /\s+/ ) || [] ).filter(
+				className => !elementsWithWhitelistClasses.includes( className )
+			);
+
+			// Avoid applying classes to elements that already have one.
+			if ( classList.length > 1 ) {
+				return;
+			}
+
+			// Add the specified classes
+			if ( typeof classesOrCallback === 'function' ) {
+				const elementClasses = classesOrCallback( $element );
+
+				if ( Array.isArray( elementClasses ) ) {
+					$element.addClass( elementClasses.join( ' ' ) );
+				} else if ( typeof elementClasses === 'string' ) {
+					$element.addClass( elementClasses );
+				}
+			} else if ( Array.isArray( classesOrCallback ) ) {
+				$element.addClass( classesOrCallback.join( ' ' ) );
+			} else {
+				$element.addClass( classesOrCallback );
+			}
+		} );
+	}
+
+	return $.html();
+};
+
+/**
+ * Checks if the element itself or any of its parents has the specified class.
+ *
+ * @param $element - The jQuery element to check.
+ * @param className - The class name to look for.
+ * @returns True if the element or any parent has the class, false otherwise.
+ */
+function hasClassOrParentWithClass( $element, className ) {
+	return $element.hasClass( className ) || $element.parents( `.${ className }` ).length > 0;
+}

package/scripts/utils/{pipe.js → compose.js}

@@ -12,6 +12,6 @@
  * @param {*} value - The initial value to be processed by the functions.
  * @returns {*} The final result after all functions have been applied.
  */
-module.exports = function pipe( ...fns ) {
+module.exports = function compose( ...fns ) {
 	return value => fns.reduce( ( acc, fn ) => fn( acc ), value );
 };

package/scripts/utils/concat-url-parts.js

@@ -7,13 +7,13 @@
 
 const dropInitSlash = require( './drop-init-slash' );
 const dropTrailingSlash = require( './drop-trailing-slash' );
-const pipe = require( './pipe' );
+const compose = require( './compose' );
 
 module.exports = function concatUrlParts( ...urls ) {
 	return (
 		urls
 			.filter( Boolean )
-			.map( pipe( dropTrailingSlash, dropInitSlash ) )
+			.map( compose( dropTrailingSlash, dropInitSlash ) )
 			.join( '/' )
 	);
 };

package/scripts/utils/pug-to-xml-binding/parser/xml-components-parser.js

@@ -11,7 +11,7 @@ const removeIndentation = require( '../../remove-indentation.js' );
 const ParserCursor = require( '../../parser-cursor.js' );
 
 /**
- * A parser for converting text containing HTML-like markup into a tree structure.
+ * A parser for converting markdown containing HTML-like markup into a tree structure.
  * Uses a cursor-based approach with backtracking capabilities for robust parsing.
  */
 module.exports = class XMLComponentsParser {
@@ -292,32 +292,28 @@ module.exports = class XMLComponentsParser {
 	 * @returns The content between backticks including the backticks themselves.
 	 */
 	#eatBacktick = this.#tryOrRestoreCursor( () => {
-		let acc = '`';
-		this.#cursor.index++;
+		const { text } = this.#cursor;
+		const startIndex = this.#cursor.index;
 
-		while ( this.#cursor.index < this.#cursor.text.length ) {
-			const ch = this.#cursor.text[ this.#cursor.index ];
+		let backtickSequence = '';
 
-			if ( ch === '`' ) {
-				acc += '`';
-				this.#cursor.index++;
+		while ( this.#cursor.index < text.length && text[ this.#cursor.index ] === '`' ) {
+			backtickSequence += '`';
+			this.#cursor.index++;
+		}
+
+		const openingBackticksLength = backtickSequence.length;
+
+		while ( this.#cursor.index < text.length ) {
+			if ( text.substring( this.#cursor.index, this.#cursor.index + openingBackticksLength ) === backtickSequence ) {
+				this.#cursor.index += openingBackticksLength;
 				break;
 			}
 
-			if ( ch === '\\' ) {
-				acc += '\\';
-				this.#cursor.index++;
-				if ( this.#cursor.index < this.#cursor.text.length ) {
-					acc += this.#cursor.text[ this.#cursor.index ];
-					this.#cursor.index++;
-				}
-			} else {
-				acc += ch;
-				this.#cursor.index++;
-			}
+			this.#cursor.index++;
 		}
 
-		return acc;
+		return text.substring( startIndex, this.#cursor.index );
 	} );
 
 	/**

package/src/helpers/resolve-path.js

@@ -0,0 +1,13 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Wrapper around `require.resolve()` to allow mocking it in tests.
+ */
+module.exports = function resolvePath( path, options ) {
+	return require.resolve( path, options );
+};

package/src/hexo/get-repo-urls.js

@@ -17,7 +17,7 @@ module.exports = ( {
 	guidesToRepos.default = defaultRepoUrl;
 
 	for ( const item of packages ) {
-		const packageRepoUrl = getRepoUrl( upath.join( rootPath, item.path ) );
+		const packageRepoUrl = getRepoUrl( upath.resolve( rootPath, item.path ) );
 		globSync( upath.join( rootPath, item.path, 'docs', '**', '*.md' ) )
 			.map( p => upath.normalize( p ) )
 			.map( p => p.replace( upath.join( rootPath, item.path, 'docs' ), '' ) )

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

@@ -58,13 +58,13 @@ module.exports = ( rootPath, config, options ) => {
 	if ( config.items && Array.isArray( config.items ) ) {
 		for ( const item of config.items ) {
 			hexoManager.addOriginPath(
-				upath.join( rootPath, item.path, config.path ),
-				upath.join( hexoManager.getSourceDir(), BASE_PATH )
+				upath.resolve( rootPath, item.path, config.path ),
+				upath.resolve( hexoManager.getSourceDir(), BASE_PATH )
 			);
 
 			promises.push( copyDocFiles(
-				upath.join( rootPath, item.path, config.path ),
-				upath.join( hexoManager.getSourceDir(), BASE_PATH ),
+				upath.resolve( rootPath, item.path, config.path ),
+				upath.resolve( hexoManager.getSourceDir(), BASE_PATH ),
 				{
 					match,
 					allOutputPaths,

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

@@ -7,6 +7,7 @@
 
 const upath = require( 'upath' );
 const fs = require( 'fs-extra' );
+const resolvePath = require( '../helpers/resolve-path' );
 
 /**
  * @returns {Promise<void>}
@@ -19,7 +20,9 @@ module.exports = async function copyProjectIcons( projectGlobals, buildDirectory
 		const destinationIconsPath = upath.join( buildDirectory, projectDetails.BASE_PATH, 'assets', 'icons' );
 
 		for ( const [ sourceFile, destinationName ] of projectDetails._icons ) {
-			const fullSourcePath = upath.join( projectDetails.config.projectRootPath, 'node_modules', sourceFile );
+			const fullSourcePath = resolvePath( sourceFile, {
+				paths: [ projectDetails.config.projectRootPath ]
+			} );
 			const fullDestinationPath = upath.join( destinationIconsPath, destinationName );
 
 			try {

package/themes/umberto/src/gloria/js/components/iframe.js

@@ -71,10 +71,7 @@ export class IFrame extends BaseComponent {
 	 * @param content - HTML content to load
 	 */
 	setContent( content ) {
-		const iframe = this.elements.iframe;
-		const iframeDocument = iframe.contentDocument || iframe.contentWindow?.document;
-
-		const wrappedHTML = `
+		this.elements.iframe.srcdoc = `
 			<!DOCTYPE html>
 			${ content }
 			${ this.config.autoResize ? `
@@ -91,12 +88,6 @@ export class IFrame extends BaseComponent {
 			</script>
 			` : '' }
 		`;
-
-		if ( iframeDocument ) {
-			iframeDocument.open();
-			iframeDocument.write( wrappedHTML );
-			iframeDocument.close();
-		}
 	}
 
 	/**

package/themes/umberto/src/gloria/js/helpers/{pipe.js → compose.js}

@@ -3,6 +3,6 @@
  * For licensing, see LICENSE.md.
  */
 
-export function pipe( ...fns ) {
+export function compose( ...fns ) {
 	return value => fns.reduce( ( acc, fn ) => fn( acc ), value );
 }

package/themes/umberto/src/gloria/js/modules/algolia-search.js

@@ -6,7 +6,7 @@
 import { BaseComponent } from '../components/base-component';
 import { identity } from '../helpers/identity';
 import { injectScript } from '../helpers/inject-script';
-import { pipe } from '../helpers/pipe';
+import { compose } from '../helpers/compose';
 
 const DOCSEARCH_JS_URL = 'https://cdn.jsdelivr.net/npm/@docsearch/js@3.9.0/dist/umd/index.min.js';
 
@@ -67,7 +67,7 @@ export class AlgoliaSearch extends BaseComponent {
 
 				client.search = async ( options, ...rest ) => {
 					const { results: [ firstResult ] } = await originalSearch( options, ...rest );
-					const mappedResults = pipe(
+					const mappedResults = compose(
 						filterByTags( { slug, tags } ),
 						boostByTags( boost.tags )
 					)( firstResult.hits );
@@ -110,7 +110,7 @@ function boostByTags( tags ) {
 		return identity;
 	}
 
-	return pipe(
+	return compose(
 		groupByTag,
 		sortObjectKeysByIndices( tags ),
 		Object.values,