umberto 9.0.0 → 9.1.0

package/src/api-builder/classes/description-parser.js

@@ -6,7 +6,10 @@
 'use strict';
 
 const { styleText } = require( 'util' );
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll, selectOne } = require( 'css-select' );
+const { replaceElement, removeElement, appendChild } = require( 'domutils' );
 const splitLongname = require( '../../helpers/split-longname' );
 const macroReplacer = require( '../../tasks/macro-replacer' );
 const findTargetDoclet = require( '../utils/findtargetdoclet' );
@@ -72,27 +75,29 @@ module.exports = class DescriptionParser {
 	 * @returns {Object}.content Full description.
 	 */
 	_splitToExcerptAndContent( str, { withExcerpt = false } = {} ) {
-		if ( withExcerpt ) {
-			if ( !str.startsWith( '<p>' ) ) {
-				return {
-					excerpt: '',
-					content: str
-				};
-			}
-
-			const $ = cheerio.load( str, null, false );
-			const excerpt = $( 'p' ).first().remove().html();
-			const content = $.html();
-
+		if ( !withExcerpt ) {
 			return {
-				excerpt,
-				content
+				content: str
 			};
-		} else {
+		}
+
+		if ( !str.startsWith( '<p>' ) ) {
 			return {
+				excerpt: '',
 				content: str
 			};
 		}
+
+		const doc = parseDocument( str );
+		const firstParagraph = selectOne( 'p', doc );
+		const excerpt = render( firstParagraph.children || [] );
+
+		removeElement( firstParagraph );
+
+		return {
+			excerpt,
+			content: render( doc )
+		};
 	}
 
 	/**
@@ -361,16 +366,16 @@ module.exports = class DescriptionParser {
 			return data;
 		}
 
-		const $ = cheerio.load( data, null, false );
+		const doc = parseDocument( data );
 
-		$( ':header' ).replaceWith( ( i, item ) => {
-			const headerLevel = Number( item.name.slice( -1 ) );
+		for ( const header of selectAll( 'h1,h2,h3,h4,h5,h6', doc ) ) {
+			const headerLevel = Number( header.name.slice( -1 ) );
 			const newHeaderLevel = headerLevel + decreaseLevel <= 6 ? headerLevel + decreaseLevel : 6;
 
-			return cheerio.load( `<h${ newHeaderLevel }></h${ newHeaderLevel }>` )( `h${ newHeaderLevel }` ).append( $( item ).html() );
-		} );
+			header.name = `h${ newHeaderLevel }`;
+		}
 
-		return $.html();
+		return render( doc );
 	}
 
 	/**
@@ -383,36 +388,38 @@ module.exports = class DescriptionParser {
 			return str;
 		}
 
-		const $ = cheerio.load( str, null, false );
+		const doc = parseDocument( str );
 		const theme = options.theme;
 
 		if ( theme === 'gloria' ) {
-			$( 'pre' ).each( function() {
-				const $code = $( this ).find( 'code' );
+			for ( const pre of selectAll( 'pre', doc ) ) {
+				const codeEl = selectOne( 'code', pre );
 
-				if ( !$code || !$code.length ) {
-					return;
+				if ( !codeEl ) {
+					continue;
 				}
 
 				// Get the language from the class (e.g., "language-js" -> "js")
-				const language = $code.attr( 'class' ) ?
-					$code.attr( 'class' ).replace( 'doc', '' ).replace( 'language-', '' ).replace( 'ts', 'typescript' ).trim() :
+				const classAttr = codeEl.attribs && codeEl.attribs.class ? codeEl.attribs.class : null;
+				const language = classAttr ?
+					classAttr.replace( 'doc', '' ).replace( 'language-', '' ).replace( 'ts', 'typescript' ).trim() :
 					null;
 
 				// Get the code content
-				const code = $code.html();
+				const code = render( codeEl.children || [] );
 
-				// Use the render-pug-component utility
+				// Use the render-pug-component utility.
 				const html = renderCodeBlockPug( {
 					language,
 					code
 				} );
 
-				$( this ).replaceWith( html );
-			} );
+				replaceElement( pre, parseFirstElement( html ) );
+			}
 		} else {
-			$( 'pre[class~="source"]' ).each( function() {
-				let code = $( this ).html();
+			for ( const pre of selectAll( 'pre.source', doc ) ) {
+				let code = render( pre.children || [] );
+
 				const begin = /<code> {4}/.exec( code );
 
 				if ( begin ) {
@@ -421,11 +428,11 @@ module.exports = class DescriptionParser {
 					} );
 				}
 
-				$( this ).html( code );
-			} );
+				setInnerHTML( pre, code );
+			}
 		}
 
-		return $.html();
+		return render( doc );
 	}
 
 	_macrosReplacer( fullText ) {
@@ -442,3 +449,35 @@ function composeFunctions( ...fns ) {
 		return result;
 	};
 }
+
+/**
+ * Helper: parses an HTML fragment and returns the first element node.
+ */
+function parseFirstElement( html ) {
+	const frag = parseDocument( html );
+	const body = selectOne( 'body', frag );
+	const nodes = body ? body.children : frag.children;
+
+	for ( const node of nodes || [] ) {
+		if ( node && node.type === 'tag' ) {
+			return node;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Helper: sets element's inner HTML using a fragment string.
+ */
+function setInnerHTML( element, html ) {
+	const frag = parseDocument( html );
+	const body = selectOne( 'body', frag );
+	const nodes = body ? body.children : frag.children;
+
+	element.children = [];
+
+	for ( const node of nodes || [] ) {
+		appendChild( element, node );
+	}
+}

package/src/data-converter/converters/jsduck2umberto.js

@@ -5,7 +5,11 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll, selectOne } = require( 'css-select' );
+const { getAttributeValue, textContent, replaceElement } = require( 'domutils' );
+
 const keyNameMap = {
 	tagname: {
 		name: 'kind',
@@ -161,16 +165,22 @@ function tagnameAdapter( item ) {
 
 function docAdapter( item ) {
 	const description = item.doc;
-	const $ = cheerio.load( description, null, false );
+	const doc = parseDocument( description, { decodeEntities: false } );
 
-	$( 'a' ).each( function() {
-		const href = $( this ).attr( 'href' );
-		const linkText = $( this ).text();
+	for ( const a of selectAll( 'a', doc ) ) {
+		const href = getAttributeValue( a, 'href' );
+		const linkText = textContent( a );
+		const original = render( a, { encodeEntities: false } );
 
-		$( this ).replaceWith( fixLink( href, linkText, $( this ).toString() ) );
-	} );
+		const replacementHtml = fixLink( href, linkText, original );
+		const replacementNode = parseFirstNode( replacementHtml );
 
-	return $.html();
+		if ( replacementNode ) {
+			replaceElement( a, replacementNode );
+		}
+	}
+
+	return render( doc, { encodeEntities: false } );
 }
 
 function fixLink( href, linkText, original ) {
@@ -263,16 +273,19 @@ function overridesAdapter( item ) {
 	const overrides = item.overrides || [];
 
 	return overrides.map( o => {
-		const $ = cheerio.load( o.link, null, false );
+		const doc = parseDocument( o.link );
 
-		$( 'a' ).each( function() {
-			const href = $( this ).attr( 'href' );
-			const linkText = $( this ).text();
+		for ( const a of selectAll( 'a', doc ) ) {
+			const replacementHtml = fixLink(
+				getAttributeValue( a, 'href' ),
+				textContent( a ),
+				render( a )
+			);
 
-			$( this ).replaceWith( fixLink( href, linkText, $( this ).toString() ) );
-		} );
+			replaceElement( a, parseFirstNode( replacementHtml ) );
+		}
 
-		o.link = $.html();
+		o.link = render( doc );
 
 		return o;
 	} );
@@ -300,3 +313,18 @@ function toArray( item ) {
 
 	return [];
 }
+
+/**
+ * Parses an HTML fragment and returns the first node (element or text).
+ */
+function parseFirstNode( html ) {
+	const doc = parseDocument( html );
+	const body = selectOne( 'body', doc );
+	const nodes = body ? body.children : doc.children;
+
+	if ( nodes && nodes.length ) {
+		return nodes[ 0 ];
+	}
+
+	return null;
+}

package/src/hexo/filter/project-locals.js

@@ -21,6 +21,7 @@ const umbertoVersion = require( '../../../package.json' ).version;
  * @param {Object} googletagmanager Google Tag Manager config.
  * @param {Object} googleanalytics Google Analytics config.
  * @param {Object} kapa Kapa.ai config.
+ * @param {Object} sentry Sentry config.
  * @param {Object} vwo Visual Website Optimizer config.
  * @param {Object} feedbackWidget Feedback widget config
  * @param {Array} extraStylePaths Paths to extra external css.
@@ -38,6 +39,7 @@ module.exports = ( ctx, {
 	googletagmanager,
 	googleanalytics,
 	kapa,
+	sentry,
 	promobar,
 	vwo,
 	feedbackWidget,
@@ -108,6 +110,7 @@ module.exports = ( ctx, {
 		locals.googletagmanager = googletagmanager;
 		locals.googleanalytics = googleanalytics;
 		locals.kapa = kapa;
+		locals.sentry = sentry;
 		locals.promobar = promobar;
 		locals.vwo = vwo;
 		locals.feedbackWidget = feedbackWidget;

package/src/sdk-builder/get-sdk-sources.js

@@ -8,7 +8,16 @@
 const fs = require( 'fs' );
 const upath = require( 'upath' );
 const { globSync } = require( 'glob' );
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { cloneNode, Text } = require( 'domhandler' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll, selectOne } = require( 'css-select' );
+const {
+	getAttributeValue,
+	hasAttrib,
+	textContent,
+	getName
+} = require( 'domutils' );
 
 const SDK_SELECTOR = 'meta[name="sdk-samples"]';
 
@@ -18,53 +27,66 @@ module.exports = sourcePath => {
 
 	for ( const filePath of filePaths ) {
 		const content = fs.readFileSync( filePath, { encoding: 'utf8' } );
-		const $ = cheerio.load( content, null, false );
-		const samplesNames = $( SDK_SELECTOR ).attr( 'content' ) ? $( SDK_SELECTOR ).attr( 'content' ).split( '|' ) : null;
+		const doc = parseDocument( content );
+		const sdkMeta = selectOne( SDK_SELECTOR, doc );
+		const samplesNames = sdkMeta && getAttributeValue( sdkMeta, 'content' ) ?
+			getAttributeValue( sdkMeta, 'content' ).split( '|' ) :
+			null;
+
 		const samples = samplesNames ? [] : null;
 		const meta = {};
 
 		if ( samplesNames ) {
-			for ( const sample of samplesNames.entries() ) {
+			for ( const [ index, name ] of samplesNames.entries() ) {
 				const bodyItems = [];
 				const headItems = [];
 				const flags = {};
-				$( `[data-sample*="${ sample[ 0 ] + 1 }"]` ).map( ( i, el ) => {
-					const element = $( el ).clone();
+
+				for ( const el of selectAll( `[data-sample*="${ index + 1 }"]`, doc ) ) {
+					const element = cloneNode( el, true );
 					const ret = {};
-					const outputArray = $( el ).parents( 'head' ).length ? headItems : bodyItems;
+					const outputArray = isInsideHead( el ) ? headItems : bodyItems;
+
+					if ( hasAttrib( el, 'type' ) && getAttributeValue( el, 'type' ) === 'template' ) {
+						const source = textContent( el )
+							.replace( /&lt;/g, '<' )
+							.replace( /&gt;/g, '>' );
+
+						outputArray.push( { source } );
+						continue;
+					}
+
+					if ( hasAttrib( element, 'data-sample-short' ) ) {
+						element.children = [ new Text( '{%SHORT_EDITOR_CONTENT%}' ) ];
+						ret.short = true;
+					}
+
+					if (
+						hasAttrib( element, 'data-sample-preservewhitespace' ) ||
+						hasAttrib( element, 'data-sample-preserve-whitespace' )
+					) {
+						ret.preserveWhitespace = true;
+					}
 
-					if ( $( el ).is( '[type=template]' ) ) {
-						// Template code support
-						outputArray.push( {
-							source: $( el ).text().replace( /&lt;/g, '<' ).replace( /&gt;/g, '>' )
-						} );
+					if ( hasAttrib( element, 'data-sample-template' ) && !flags.template ) {
+						flags.template = getAttributeValue( element, 'data-sample-template' );
+					}
+
+					if ( hasAttrib( element, 'data-sample-highlighter' ) && !flags.highlighter ) {
+						flags.highlighter = getAttributeValue( element, 'data-sample-highlighter' );
+					}
+
+					if ( hasAttrib( element, 'data-sample-strip-outer-tag' ) ) {
+						ret.source = render( element.children || [] ).replace( /^\n|\n$/g, '' );
 					} else {
-						if ( element.is( '[data-sample-short]' ) ) {
-							element.text( '{%SHORT_EDITOR_CONTENT%}' );
-							ret.short = true;
-						}
-						if ( element.is( '[data-sample-preserveWhitespace]' ) || element.is( '[data-sample-preserve-whitespace]' ) ) {
-							ret.preserveWhitespace = true;
-						}
-						if ( element.is( '[data-sample-template]' ) && !flags.template ) {
-							flags.template = element.data( 'sample-template' );
-						}
-						if ( element.is( '[data-sample-highlighter]' ) && !flags.highlighter ) {
-							flags.highlighter = element.data( 'sample-highlighter' );
-						}
-
-						if ( element.is( '[data-sample-strip-outer-tag]' ) ) {
-							ret.source = element.html().replace( /^\n|\n$/g, '' );
-						} else {
-							ret.source = $.html( element ).replace( /\s?data-sample(-[\w-]+)?="[^"]*?"/g, '' ); // Strip data attributes
-						}
-
-						outputArray.push( ret );
+						ret.source = render( element ).replace( /\s?data-sample(-[\w-]+)?="[^"]*?"/g, '' );
 					}
-				} );
+
+					outputArray.push( ret );
+				}
 
 				samples.push( {
-					name: sample[ 1 ],
+					name,
 					bodyItems,
 					headItems,
 					flags
@@ -72,23 +94,38 @@ module.exports = sourcePath => {
 			}
 		}
 
-		$( 'meta[name^="sdk-"]' ).map( ( i, el ) => {
-			const keyName = $( el ).attr( 'name' ).replace( 'sdk-', '' );
+		for ( const el of selectAll( 'meta[name^="sdk-"]', doc ) ) {
+			const keyName = getAttributeValue( el, 'name' ).replace( 'sdk-', '' );
 
-			meta[ keyName ] = $( el ).attr( 'content' );
-		} );
+			meta[ keyName ] = getAttributeValue( el, 'content' );
+		}
+
+		const sdkContents = selectOne( '.sdk-contents', doc );
+		const contentHtml = render( sdkContents.children || [] );
+		const presetVersion = getAttributeValue( sdkContents, 'data-cke-preset' );
 
 		files.push( {
 			name: upath.basename( filePath, '.html' ),
-			description: $( 'meta[name="description"]' ).attr( 'content' ),
-			title: $( 'title' ).text(),
-			content: $( '.sdk-contents' ).html(),
-			source: $.html(),
+			description: getAttributeValue( selectOne( 'meta[name="description"]', doc ), 'content' ),
+			title: textContent( selectOne( 'title', doc ) ),
+			content: contentHtml,
+			source: render( doc ),
 			path: upath.relative( sourcePath, filePath ),
-			presetVersion: $( '.sdk-contents' ).data( 'cke-preset' ),
+			presetVersion,
 			sdkSamples: samples,
 			meta
 		} );
 	}
+
 	return files;
 };
+
+function isInsideHead( node ) {
+	for ( let p = node && node.parent; p; p = p.parent ) {
+		if ( getName( p ) === 'head' ) {
+			return true;
+		}
+	}
+
+	return false;
+}

package/src/tasks/build-documentation.js

@@ -146,6 +146,7 @@ module.exports = options => {
 				googletagmanager: mainConfig.googletagmanager,
 				googleanalytics: mainConfig.googleanalytics,
 				kapa: mainConfig.kapa,
+				sentry: mainConfig.sentry,
 				promobar: mainConfig.promobar,
 				sitemap: mainConfig.sitemap,
 				vwo: mainConfig.vwo,
@@ -291,6 +292,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 				googletagmanager: options.googletagmanager,
 				googleanalytics: options.googleanalytics,
 				kapa: options.kapa,
+				sentry: options.sentry,
 				promobar: options.promobar,
 				sitemap: options.sitemap,
 				vwo: options.vwo,
@@ -370,6 +372,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			googletagmanager: options.googletagmanager,
 			googleanalytics: options.googleanalytics,
 			kapa: options.kapa,
+			sentry: options.sentry,
 			promobar: options.promobar,
 			quickNavigationProjects: options.quickNavigationProjects,
 			vwo: options.vwo,
@@ -477,6 +480,7 @@ async function buildApis( projectConfigs, options = {} ) {
 				googletagmanager: options.googletagmanager,
 				googleanalytics: options.googleanalytics,
 				kapa: options.kapa,
+				sentry: options.sentry,
 				promobar: options.promobar,
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,

package/src/tasks/minify-html.js

@@ -20,7 +20,7 @@ module.exports = async function minifyHtml( outputDir ) {
 
 	const pool = new TinyPool( {
 		runtime: 'child_process',
-		filename: require.resolve( './minify-worker.js' )
+		filename: require.resolve( './minify-html-worker.js' )
 	} );
 
 	try {

package/src/tasks/validate-links-collect-worker.js

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const fs = require( 'fs-extra' );
+const upath = require( 'upath' );
+const { isMaskedID } = require( '../../scripts/utils/random-id' );
+
+module.exports = function( { chunk } ) {
+	const links = [];
+
+	for ( const filePath of chunk ) {
+		links.push( upath.resolve( filePath ) );
+		links.push( upath.resolve( filePath + '#' ) );
+
+		const content = fs.readFileSync( filePath, 'utf-8' );
+		// 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-' ) ) {
+				links.push( upath.resolve( `${ filePath }#${ id }` ) );
+			}
+		}
+	}
+
+	return links;
+};

package/src/tasks/validate-links-worker.js

@@ -0,0 +1,127 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const fs = require( 'fs-extra' );
+const upath = require( 'upath' );
+const { parseDocument } = require( 'htmlparser2' );
+
+/**
+ * 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>}
+ */
+module.exports = function( { 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 } of linkElements ) {
+			if ( href.endsWith( '/' ) && !href.includes( '#' ) ) {
+				href += 'index.html';
+			}
+
+			let resolvedPath = getResolvedPath( href, filePath, { publicDir: options.publicDir } );
+
+			if ( options.skipApi && resolvedPath.includes( '/api/' ) ) {
+				continue;
+			}
+
+			if ( resolvedPath.includes( '/latest/' ) ) {
+				const projectInfo = options.projectsInfo ?
+					options.projectsInfo.find( i => resolvedPath.includes( `/${ i.slug }/` ) ) :
+					null;
+				const projectVersion = projectInfo ? projectInfo.version : 'latest';
+				resolvedPath = resolvedPath.replace( '/latest/', `/${ projectVersion }/` );
+			}
+
+			if ( options.projectsInfo ) {
+				const isCorrectLocalPath = options.projectsInfo.some( info => {
+					return resolvedPath.includes( info.basePath );
+				} );
+
+				if ( !isCorrectLocalPath ) {
+					continue;
+				}
+			}
+
+			if ( !links.has( resolvedPath ) ) {
+				invalidHrefs.push( { href, text, filePath } );
+			}
+		}
+
+		if ( invalidHrefs.length ) {
+			errors.push( { filePath, invalidHrefs } );
+		}
+	}
+
+	return errors;
+};
+
+/**
+ * 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
+ * @returns {string}
+ */
+function getResolvedPath( href, filePath, options ) {
+	if ( href.startsWith( '#' ) ) {
+		return upath.resolve( filePath + href );
+	}
+
+	if ( href.startsWith( '/' ) ) {
+		const commonPoint = href.match( /^\/[^/]+/ )[ 0 ];
+
+		// The `commonPoint` should be removed from the end of the `options.publicDir` string.
+		// It may happen that `commonPoint` is present at the middle of that path and removing it produces invalid results.
+		// See: #909.
+		const regExpCommonPoint = new RegExp( commonPoint + '$' );
+
+		return upath.resolve( options.publicDir.replace( regExpCommonPoint, '' ) + href );
+	}
+
+	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 ( !skipValidation && text && href && !href.match( /[a-z:]*\/\// ) && !href.match( /mailto:/ ) ) {
+			linkElements.push( { href, text } );
+		}
+	}
+
+	if ( !node.childNodes ) {
+		return;
+	}
+
+	for ( const childNode of node.childNodes ) {
+		processNode( childNode, linkElements );
+	}
+}