umberto 9.0.0 → 9.1.1

package/scripts/utils/spritesheet-svg.js

@@ -5,179 +5,159 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
 const fs = require( 'fs' );
 const path = require( 'path' );
+const { parseDocument } = require( 'htmlparser2' );
+const { Element, cloneNode } = require( 'domhandler' );
+const { selectAll, selectOne } = require( 'css-select' );
+const { getAttributeValue, removeElement, appendChild, prependChild } = require( 'domutils' );
 
-const HexoManager = require( '../../src/hexo-manager' );
+module.exports = function spritesheetSvg( doc, themeDir ) {
+	const elements = selectAll( '[data-spritesheet-svg]', doc );
 
-/**
- * Cache for parsed SVG elements.
- */
-const SVG_CACHE = new Map();
-
-module.exports = function spritesheetSvg( str, isDocument = true ) {
-	const $ = cheerio.load( str, null, isDocument );
-	const elements = $( '[data-spritesheet-svg]' );
-
-	// Skip if there are no elements with data-spritesheet-svg
+	// Skip if there are no elements with data-spritesheet-svg.
 	if ( elements.length === 0 ) {
-		return str;
+		return doc;
 	}
 
-	// Collect all unique SVG files to include in the spritesheet
+	// Collect all unique SVG files to include in the spritesheet.
 	const svgFiles = new Map();
 
-	// Helper function to extract SVG file information
-	function collectSvgFileInfo( element ) {
-		const svgPath = element.attr( 'data-spritesheet-svg' );
-		const iconId = element.attr( 'data-spritesheet-id' );
+	// Helper function to extract SVG file information.
+	function collectSvgFileInfo( el ) {
+		const svgPath = getAttributeValue( el, 'data-spritesheet-svg' );
+		const iconId = getAttributeValue( el, 'data-spritesheet-id' );
 
-		if ( !svgFiles.has( iconId ) ) {
+		if ( iconId && !svgFiles.has( iconId ) ) {
 			svgFiles.set( iconId, svgPath );
 		}
 	}
 
-	// Process normal SVG elements
-	elements.each( function() {
-		const $element = $( this );
-
-		collectSvgFileInfo( $element );
-	} );
-
-	// Process and remove preload elements
-	const preloadElements = $( '[data-spritesheet-preload="true"]' );
-	preloadElements.each( function() {
-		const $element = $( this );
+	// Process normal SVG elements.
+	for ( const el of elements ) {
+		collectSvgFileInfo( el );
+	}
 
-		collectSvgFileInfo( $element );
-		$element.remove();
-	} );
+	// Process and remove preload elements.
+	for ( const el of selectAll( '[data-spritesheet-preload="true"]', doc ) ) {
+		collectSvgFileInfo( el );
+		removeElement( el );
+	}
 
 	if ( svgFiles.size === 0 ) {
-		return str;
+		return doc;
 	}
 
-	// Create spritesheet and get viewBox data
-	const { spritesheetElement, iconViewBoxes } = createSpritesheet( $, svgFiles );
+	// Create spritesheet and get viewBox data.
+	const { spritesheetElement, iconViewBoxes } = createSpritesheet( svgFiles, themeDir );
 
-	// Add spritesheet to the beginning of the body
-	if ( $( 'body' ).length ) {
-		$( 'body' ).prepend( spritesheetElement );
-	}
+	// Add spritesheet to the beginning of the body.
+	prependChild( selectOne( 'body', doc ), spritesheetElement );
 
-	// Set viewBox for original SVG elements
-	elements.each( function() {
-		const element = $( this );
-		const iconId = element.attr( 'data-spritesheet-id' );
+	// Set viewBox for original SVG elements.
+	for ( const el of elements ) {
+		const iconId = getAttributeValue( el, 'data-spritesheet-id' );
 		const viewBox = iconViewBoxes.get( iconId );
 
-		if ( viewBox && this.tagName.toLowerCase() === 'svg' ) {
-			element.attr( 'viewBox', viewBox );
+		if ( viewBox && el.name === 'svg' ) {
+			el.attribs.viewBox = viewBox;
 		}
-	} );
+	}
 
-	$( '[data-spritesheet-svg]' ).removeAttr( 'data-spritesheet-svg' );
-	$( '[data-spritesheet-id]' ).removeAttr( 'data-spritesheet-id' );
+	for ( const el of selectAll( '[data-spritesheet-svg]', doc ) ) {
+		delete el.attribs[ 'data-spritesheet-svg' ];
+	}
+
+	for ( const el of selectAll( '[data-spritesheet-id]', doc ) ) {
+		delete el.attribs[ 'data-spritesheet-id' ];
+	}
 
-	return $.html();
+	return doc;
 };
 
 /**
  * Creates an SVG spritesheet from the provided SVG files.
  * Returns an object containing the spritesheet element and a map of icon IDs to their viewBox strings.
  */
-function createSpritesheet( $, svgFiles ) {
+function createSpritesheet( svgFiles, themeDir ) {
 	const symbols = [];
 	const iconViewBoxes = new Map();
 
 	for ( const [ iconId, svgPath ] of svgFiles.entries() ) {
-		const absolutePath = path.join( HexoManager.hexo.theme_dir, svgPath );
+		const absolutePath = path.join( themeDir, svgPath );
 
 		if ( !fs.existsSync( absolutePath ) ) {
 			console.warn( `SVG file not found: ${ absolutePath }` );
 			continue;
 		}
 
-		// Check if we have the SVG in cache
-		if ( !SVG_CACHE.has( absolutePath ) ) {
-			try {
-				const svgContent = fs.readFileSync( absolutePath, 'utf8' );
-				const $svg = cheerio.load( svgContent, { xmlMode: true } )( 'svg' );
-				SVG_CACHE.set( absolutePath, $svg );
-			} catch ( error ) {
-				console.error( `Error reading SVG file: ${ absolutePath }`, error );
-				continue;
-			}
-		}
+		const svgContent = fs.readFileSync( absolutePath, 'utf8' );
+		const svgDoc = parseDocument( svgContent, { xmlMode: true } );
+		const svgRoot = selectOne( 'svg', svgDoc );
 
-		const $svg = SVG_CACHE.get( absolutePath ).clone();
+		if ( !svgRoot ) {
+			console.warn( `No <svg> root element found in: ${ absolutePath }` );
+			continue;
+		}
 
-		// Create symbol element from SVG
-		const $symbol = $( '<symbol></symbol>' );
-		$symbol.attr( 'id', iconId );
+		// Create <symbol> element from SVG.
+		const symbolEl = new Element( 'symbol', { id: iconId } );
 
-		// Copy viewBox and other relevant attributes
+		// Compute and set viewBox on <symbol>, also store for consumers.
 		let viewBoxValue;
-		if ( $svg.attr( 'viewBox' ) ) {
-			viewBoxValue = $svg.attr( 'viewBox' );
-		} else if ( $svg.attr( 'width' ) && $svg.attr( 'height' ) ) {
-			viewBoxValue = `0 0 ${ $svg.attr( 'width' ) } ${ $svg.attr( 'height' ) }`;
+
+		if ( svgRoot.attribs.viewBox ) {
+			viewBoxValue = svgRoot.attribs.viewBox;
+		} else if ( svgRoot.attribs.width && svgRoot.attribs.height ) {
+			viewBoxValue = `0 0 ${ svgRoot.attribs.width } ${ svgRoot.attribs.height }`;
 		}
 
 		if ( viewBoxValue ) {
-			$symbol.attr( 'viewBox', viewBoxValue );
+			symbolEl.attribs.viewBox = viewBoxValue;
 			iconViewBoxes.set( iconId, viewBoxValue );
 		}
 
-		// Copy all child elements from SVG to symbol
-		$svg.children().each( function() {
-			const $child = $( this );
-			// Skip title elements as they'll be provided by the consuming SVG
-			if ( $child[ 0 ].tagName.toLowerCase() !== 'title' ) {
-				$symbol.append( $child.clone() );
+		// Copy element children (<title> is skipped).
+		for ( const child of svgRoot.children ) {
+			if ( child && child.type === 'tag' && child.name.toLowerCase() !== 'title' ) {
+				appendChild( symbolEl, cloneNode( child, true ) );
 			}
-		} );
+		}
 
-		symbols.push(
-			resetFillColor( $, $symbol )
-		);
+		symbols.push( resetFillColor( symbolEl ) );
 	}
 
-	// Create the spritesheet container
-	const $spritesheet = $( '<svg></svg>' );
-	$spritesheet.attr( {
+	// Create the spritesheet container.
+	const spritesheet = new Element( 'svg', {
 		'class': 'svg-spritesheet',
 		'xmlns': 'http://www.w3.org/2000/svg',
 		'style': 'display: none;',
 		'aria-hidden': 'true'
 	} );
 
-	// Add all symbols to the spritesheet
-	symbols.forEach( $symbol => {
-		$spritesheet.append( $symbol );
-	} );
+	// Add all symbols to the spritesheet.
+	for ( const symbol of symbols ) {
+		appendChild( spritesheet, symbol );
+	}
 
 	return {
-		spritesheetElement: $spritesheet,
+		spritesheetElement: spritesheet,
 		iconViewBoxes
 	};
 }
 
 /**
- * Resets the fill color of an SVG element to 'currentColor'.
- * This is useful for ensuring that the SVG inherits the text color from its parent.
+ * Resets the fill color of an SVG container (e.g., <symbol>) to 'currentColor'.
+ * Ensures descendants that explicitly set 'fill' will inherit from text color in consumers.
  */
-function resetFillColor( $, $svg ) {
-	// Replace all fill attributes with the specified color.
-	$svg.find( '[fill]' ).each( function() {
-		$( this ).attr( 'fill', 'currentColor' );
-	} );
+function resetFillColor( el ) {
+	for ( const node of selectAll( '[fill]', el ) ) {
+		node.attribs.fill = 'currentColor';
+	}
 
-	// Also check the root SVG for fill attribute.
-	if ( $svg.attr( 'fill' ) ) {
-		$svg.attr( 'fill', 'currentColor' );
+	if ( el.attribs?.fill !== undefined ) {
+		el.attribs.fill = 'currentColor';
 	}
 
-	return $svg;
+	return el;
 }

package/scripts/utils/toc.js

@@ -5,10 +5,14 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { Element, Text, cloneNode } = require( 'domhandler' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll } = require( 'css-select' );
+const { appendChild, getAttributeValue, removeElement, textContent } = require( 'domutils' );
 
 module.exports = function toc( data, options = {} ) {
-	const $ = cheerio.load( data, null, false );
+	const doc = parseDocument( data );
 
 	let usedHeadings = [ 'h2', 'h3', 'h4', 'h5', 'h6' ];
 
@@ -16,56 +20,106 @@ module.exports = function toc( data, options = {} ) {
 		usedHeadings = usedHeadings.slice( 0, options.tocLimit );
 	}
 
-	usedHeadings = usedHeadings.join( ',' );
+	const selector = usedHeadings.join( ',' );
+
+	const headings = selectAll( selector, doc ).filter( heading => {
+		return !hasAncestorWithClassIn( heading, [ 'live-snippet', 'collapsing-list__item' ] );
+	} );
 
-	const headings = $( usedHeadings )
-		.filter( function() {
-			return !$( this ).parents( '.live-snippet, .collapsing-list__item' ).length;
-		} );
 	const className = options.class || 'secondary-navigation';
 
 	if ( !headings.length ) {
 		return '';
 	}
 
-	const $r = cheerio.load( `<nav class=${ className }><h3>Table of contents</h3></nav>`, null, false ); // result object
-	const tocLastLevels = [ $r( 'nav' ), 0, 0, 0, 0, 0, 0 ];
-
-	headings.each( function() {
-		const hLevel = Number( this.name[ 1 ] );
-		const id = $r( this ).attr( 'id' );
-		const text = $r( this ).find( '.headerlink' ).remove().end().text().trim()
-			// Replace the chevrons with their HTML escape characters to avoid rendering HTML in ToC.
-			.replace( /</g, '&lt;' )
-			.replace( />/g, '&gt;' );
+	const nav = new Element( 'nav', { class: className } );
+	const h3 = new Element( 'h3', {} );
+	appendChild( h3, new Text( 'Table of contents' ) );
+	appendChild( nav, h3 );
+
+	const tocLastLevels = [ nav, null, null, null, null, null, null ];
+	let lastLi = null;
+
+	for ( const heading of headings ) {
+		const hLevel = Number( heading.name[ 1 ] ); // 'h2' -> 2
+		const text = getHeadingText( heading ).trim();
+		const li = new Element( 'li', {} );
+		const a = new Element( 'a', {
+			class: 'a11y-focusable',
+			href: '#' + getAttributeValue( heading, 'id' ),
+			title: text
+		} );
 
-		const newItem = `<li><a class="a11y-focusable" href="#${ id }" title="${ text }">${ text }</a></li>`;
+		appendChild( a, new Text( text ) );
+		appendChild( li, a );
 
 		if ( tocLastLevels[ hLevel ] ) {
-			// If there already is a parent node for current heading level, append the new toc item there.
-			tocLastLevels[ hLevel ].append( newItem );
+			// Append to existing <ol> for this heading level.
+			appendChild( tocLastLevels[ hLevel ], li );
 		} else {
-			// If there's no parent node for current heading level, create it and append.
-			if ( $r( 'li' ).length ) {
-				$r( 'li' ).last().append( `<ol>${ newItem }</ol>` );
+			// No <ol> for this level yet – create it and attach to last <li> or <nav>.
+			const ol = new Element( 'ol', {} );
+			appendChild( ol, li );
+
+			if ( lastLi ) {
+				appendChild( lastLi, ol );
 			} else {
-				$r( 'nav' ).append( `<ol>${ newItem }</ol>` );
+				appendChild( nav, ol );
 			}
 
-			// Assign new created <ol> element to the helper array.
-			tocLastLevels[ hLevel ] = $r( 'ol' ).last();
+			tocLastLevels[ hLevel ] = ol;
 		}
 
-		// After adding new toc item, lower heading levels in helper array must be cleared.
-		// If e.g. level 2 <ol> was added, then level 3 nd lower <ol>s are no longer needed because they belong to upper toc nodes.
+		lastLi = li;
+
+		// Clear deeper levels; they no longer apply after adding an item at this level.
 		clearLowerLevels( tocLastLevels, hLevel );
-	} );
+	}
 
-	return $r.html();
+	return render( nav );
 };
 
 function clearLowerLevels( levels, current ) {
 	for ( let i = current + 1; i < levels.length; i++ ) {
-		levels[ i ] = 0;
+		levels[ i ] = null;
+	}
+}
+
+/**
+ * Returns true if `node` has an ancestor with any of the given classes.
+ */
+function hasAncestorWithClassIn( node, classNames ) {
+	for ( let p = node && node.parent; p; p = p.parent ) {
+		const cls = getAttributeValue( p, 'class' );
+
+		if ( !cls ) {
+			continue;
+		}
+
+		const classes = cls.split( /\s+/ ).filter( Boolean );
+
+		if ( classes.some( c => classNames.includes( c ) ) ) {
+			return true;
+		}
 	}
+
+	return false;
+}
+
+/**
+ * Returns the heading text without content from descendants with class "headerlink".
+ */
+function getHeadingText( root ) {
+	if ( !root ) {
+		return '';
+	}
+
+	// Clone so we don't mutate the original AST.
+	const clone = cloneNode( root, true );
+
+	for ( const node of selectAll( '.headerlink', clone ) ) {
+		removeElement( node );
+	}
+
+	return textContent( clone );
 }

package/src/api-builder/api-builder.js

@@ -7,7 +7,10 @@
 
 const upath = require( 'upath' );
 const fs = require( 'fs-extra' );
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { selectAll } = require( 'css-select' );
+const { textContent, removeElement } = require( 'domutils' );
+const { default: TinyPool } = require( 'tinypool' );
 const FileNameManager = require( './classes/file-name-manager' );
 const HtmlFile = require( './classes/html-file' );
 const DocDataFactory = require( './classes/doc-data-factory' );
@@ -21,11 +24,8 @@ const githubUrlUtils = require( '../helpers/github-url' );
 const getReportIssueWidgetUrl = require( '../../scripts/utils/getreportissuewidgeturl' );
 const getPageGroupHelper = require( '../../src/hexo/helper/get-page-group' );
 const findTargetDoclet = require( './utils/findtargetdoclet' );
-const writeHtmlFiles = require( '../../src/tasks/write-html-files' );
 
 const { randomId } = require( '../../scripts/utils/random-id' );
-const spritesheetSvg = require( '../../scripts/utils/spritesheet-svg' );
-const inlineSvg = require( '../../scripts/utils/inline-svg' );
 const parseHref = require( '../../scripts/utils/parse-href' );
 const hexoManager = require( '../hexo-manager' );
 
@@ -204,12 +204,18 @@ module.exports = class ApiBuilder {
 		this._buildNavTree( concated );
 		this._filterHtml = this._tmplCol.renderTemplate( '_partial/filter' );
 
-		await this._getPages( modulesData, 'module' );
-		await this._getPages( classesData, 'class' );
-		await this._getPages( interfacesData, 'interface' );
-		await this._getPages( typedefsData, 'typedef' );
-		await this._getPages( mixinsData, 'mixin' );
-		await this._getPages( namespacesData, 'namespace' );
+		const pool = new TinyPool( {
+			filename: require.resolve( './build-page-worker.js' )
+		} );
+
+		await this._getPages( pool, modulesData, 'module' );
+		await this._getPages( pool, classesData, 'class' );
+		await this._getPages( pool, interfacesData, 'interface' );
+		await this._getPages( pool, typedefsData, 'typedef' );
+		await this._getPages( pool, mixinsData, 'mixin' );
+		await this._getPages( pool, namespacesData, 'namespace' );
+
+		await pool.destroy();
 
 		this._renderedFiles = [];
 
@@ -379,34 +385,30 @@ module.exports = class ApiBuilder {
 			}
 		}
 
-		this._navTreeHtml = spritesheetSvg( this._tmplCol.renderTemplate(
-			'_partial/navtree',
-			{
-				projectLocals: {
-					apiTree: this._navTree
-				}
+		this._navTreeHtml = this._tmplCol.renderTemplate( '_partial/navtree', {
+			projectLocals: {
+				apiTree: this._navTree
 			}
-		), false );
+		} );
 	}
 
 	/**
 	 * Renders HTML of each API docs page and creates an HtmlFile instance for that page.
 	 */
-	async _getPages( items, type ) {
-		const views = [];
+	async _getPages( pool, items, type ) {
+		const jobs = [];
+		const groups = this._groups.map( g => {
+			g._url = upath.join( this._BASE_PATH, g.slug, 'index.html' );
 
-		for ( const i of items ) {
-			const data = this._getPageData( i, type );
-			const filename = this._fileNameManager.getFilename( i.longname );
+			return g;
+		} );
+
+		for ( const item of items ) {
+			const data = this._getPageData( item, type );
+			const filename = this._fileNameManager.getFilename( item.longname );
 
 			if ( filename ) {
 				const filePath = upath.join( this._destinationDir, filename );
-				const groups = this._groups.map( g => {
-					g._url = upath.join( this._BASE_PATH, g.slug, 'index.html' );
-
-					return g;
-				} );
-
 				const shortModulePath = getShortModulePath( data.longname );
 				const split = splitLongname( data.longname );
 				const splitParts = [ split.packageName, ...split.directoryNames ];
@@ -420,10 +422,20 @@ module.exports = class ApiBuilder {
 					title = `${ capitalize( data.kind ) } ${ capitalize( split.name ) }`;
 				}
 
-				const $ = data.description ? cheerio.load( data.description.content, null, false ) : cheerio.load( '', null, false );
-				const html = $.root();
-				html.find( 'pre' ).remove();
-				const desc = html.text().trim().replace( /\n/g, ' ' ).replace( / +/g, ' ' );
+				let desc = '';
+
+				if ( data.description ) {
+					const descDoc = parseDocument( data.description.content );
+
+					for ( const pre of selectAll( 'pre', descDoc ) ) {
+						removeElement( pre );
+					}
+
+					desc = textContent( descDoc )
+						.trim()
+						.replace( /\n/g, ' ' )
+						.replace( / +/g, ' ' );
+				}
 
 				// eslint-disable-next-line @stylistic/max-len
 				const metaDescription = `${ this._projectName } API Documentation. The ${ capitalize( data.kind ) } ${ data.kind === 'module' ? data.longname.replace( 'module:', '' ) : capitalize( split.name ) }.${ desc.length ? ' ' + desc : '' }`;
@@ -483,17 +495,18 @@ module.exports = class ApiBuilder {
 					filePath
 				);
 
-				let content = inlineSvg( view.content );
-
-				content = spritesheetSvg( content );
-
-				view.content = content.replaceAll( '%%_RENDERED_NAV_TREE_%%', this._navTreeHtml );
-
-				await writeHtmlFiles( [ view ] );
+				jobs.push(
+					pool.run( {
+						content: view.content,
+						navTreeHtml: this._navTreeHtml,
+						outputPath: upath.join( view.dirname, view.basename ),
+						themeDir: hexoManager.hexo.theme_dir
+					} )
+				);
 			}
 		}
 
-		return views;
+		await Promise.all( jobs );
 
 		/**
 		 * Function trim text to the last sentence.

package/src/api-builder/build-page-worker.js

@@ -0,0 +1,35 @@
+/**
+ * @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' );
+const upath = require( 'upath' );
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const inlineSvg = require( '../../scripts/utils/inline-svg' );
+const spritesheetSvg = require( '../../scripts/utils/spritesheet-svg' );
+
+module.exports = function( {
+	content,
+	navTreeHtml,
+	outputPath,
+	themeDir
+} ) {
+	let doc = parseDocument( content );
+	doc = inlineSvg( doc, themeDir );
+	doc = spritesheetSvg( doc, themeDir );
+	content = render( doc ).replaceAll( '%%_RENDERED_NAV_TREE_%%', navTreeHtml );
+
+	const dirname = upath.dirname( outputPath );
+
+	try {
+		fs.accessSync( dirname );
+	} catch {
+		fs.mkdirSync( dirname, { recursive: true } );
+	}
+
+	fs.writeFileSync( outputPath, content, 'utf-8' );
+};