umberto 7.0.2 → 8.0.0

package/scripts/utils/pug-to-xml-binding/transform-xml-tree-to-pug.js

@@ -0,0 +1,144 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Transforms XML tree structure to Pug mixin format.
+ * This module converts parsed XML nodes into Pug template syntax with proper indentation and attribute handling.
+ */
+
+'use strict';
+
+const { TreeWalkActions, walkXMLTree } = require( './parser/walk-xml-tree' );
+
+/**
+ * Transforms an XML tree structure into Pug mixin syntax.
+ *
+ * @param tree - The XML tree object to transform
+ * @param nesting - Base nesting level for indentation
+ * @param options - Configuration options
+ * @param options.nestingCharacter - Character used for indentation (default: '\t')
+ * @returns The transformed Pug mixin string
+ */
+function transformXMLTreeToPug( tree, nesting, options = {} ) {
+	const {
+		nestingCharacter = '\t',
+		parseText = str => str,
+		fallbackGlobalRequire
+	} = options;
+
+	let hasMissingImports = false;
+
+	// Walk through the XML tree and transform each node
+	const requireTags = new Set( [] );
+	const result = walkXMLTree( tree, {
+		leave( node, depth, parents ) {
+			// Calculate indentation based on nesting level and current depth
+			const indent = nestingCharacter.repeat( nesting + depth );
+
+			switch ( node.type ) {
+				case 'text': {
+					const parent = parents[ parents.length - 1 ];
+					let mappedContent = node.content;
+
+					if ( parent && parent.type === 'element' ) {
+						mappedContent = parseText( parent, mappedContent );
+					}
+
+					if ( !mappedContent ) {
+						return TreeWalkActions.remove();
+					}
+
+					return TreeWalkActions.replace( `${ indent }| ${ mappedContent }\n` );
+				}
+
+				case 'element': {
+					if ( !node.patternElement?.requires?.length ) {
+						hasMissingImports = true;
+					} else if ( !hasMissingImports ) {
+						for ( const requirePath of node.patternElement.requires ) {
+							requireTags.add( requirePath );
+						}
+					}
+
+					const mappedAttributes = (
+						node.patternElement?.attributesMapper ?
+							node.patternElement.attributesMapper( node ) :
+							node.attributes
+					);
+
+					return TreeWalkActions.replace( [
+						`${ indent }+${ node.patternElement.mixinName || node.name }(${ serializeMixinAttributes( mappedAttributes ) })`,
+						...( node.children || [] )
+					].join( '\n' ) );
+				}
+			}
+		}
+	} );
+
+	// There is no need to duplicate requires if the fallback global require is already included.
+	if ( hasMissingImports ) {
+		requireTags.clear();
+		requireTags.add( fallbackGlobalRequire );
+	}
+
+	return [
+		...Array.from( requireTags ).map( requirePath => `include ${ requirePath }` ),
+		result
+	].join( '\n' );
+}
+
+/**
+ * Serializes XML attributes into JSON format for Pug mixin parameters.
+ * Normalizes attribute names and values according to Pug conventions.
+ *
+ * @param attributes - Object containing XML attributes
+ * @returns JSON string representation of normalized attributes
+ */
+function serializeMixinAttributes( attributes ) {
+	const entries = Object.fromEntries(
+		Object
+			.entries( attributes )
+			.map( ( [ key, value ] ) => {
+				const normalizedKey = normalizeMixinAttributeName( key );
+				const normalizedValue = normalizeMixinAttributeValue( value );
+
+				return [ normalizedKey, normalizedValue ];
+			} )
+	);
+
+	return JSON.stringify( entries );
+}
+
+/**
+ * Normalizes XML attribute values to appropriate JavaScript types.
+ * Converts string representations of booleans to actual boolean values.
+ *
+ * @param value - The XML attribute value to normalize
+ * @returns Normalized value (boolean for 'true'/'false', string otherwise)
+ */
+function normalizeMixinAttributeValue( value ) {
+	if ( value === 'true' || value === '' ) {
+		return true;
+	}
+
+	if ( value === 'false' ) {
+		return false;
+	}
+
+	return value;
+}
+
+/**
+ * Normalizes attribute names from kebab-case to camelCase.
+ * e.g., data-foo-bar -> dataFooBar
+ *
+ * @param name - The kebab-case attribute name
+ * @returns The camelCase attribute name
+ */
+function normalizeMixinAttributeName( name ) {
+	return name.replace( /-([a-z])/g, g => g[ 1 ].toUpperCase() );
+}
+
+module.exports = transformXMLTreeToPug;

package/scripts/utils/random-id.js

@@ -0,0 +1,67 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const crypto = require( 'crypto' );
+
+/**
+ * Generates a random ID with a single segment. If a prefix is provided, it will be prepended to the ID.
+ *
+ * The `gen-` prefix is always used to easier extract the generated IDs from the output.
+ *
+ * @param [prefix] Optional prefix to add to the ID
+ * @param [maskable=true] Whether the ID should be replaceable by regenerateRandomIds.
+ * @return The generated ID with optional prefix
+ */
+function randomId( prefix, maskable = true ) {
+	const shortId = crypto.randomBytes( 3 ).toString( 'hex' ).substring( 0, 5 );
+
+	let id = prefix ? `${ prefix }-${ shortId }` : shortId;
+
+	if ( maskable ) {
+		id = `gen-${ id }`;
+	}
+
+	return id;
+};
+
+/**
+ * Regenerates random IDs in a string.
+ *
+ * It finds all occurrences of IDs generated by `randomId()` and replaces them with new random IDs.
+ * If an ID is repeated in the input string, it will be replaced with the same new ID.
+ * It preserves the prefix of the original ID.
+ *
+ * @param str The string to process.
+ * @returns The string with regenerated IDs.
+ */
+function regenerateRandomIds( str ) {
+	const idCache = new Map();
+	const idRegex = /(gen-(?:[a-zA-Z0-9]+-)*[a-f0-9]{5})/g;
+
+	return str.replace( idRegex, oldId => {
+		if ( idCache.has( oldId ) ) {
+			return idCache.get( oldId );
+		}
+
+		// Everything after 'gen-'.
+		const idContent = oldId.substring( 4 );
+		const parts = idContent.split( '-' );
+
+		// The ID has 1 segment at the end. If there are more parts, it means a prefix is present.
+		const prefix = parts.length > 1 ? parts.slice( 0, -1 ).join( '-' ) : undefined;
+		const newId = randomId( prefix );
+
+		idCache.set( oldId, newId );
+
+		return newId;
+	} );
+}
+
+module.exports = {
+	randomId,
+	regenerateRandomIds
+};

package/scripts/utils/remove-indentation.js

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Removes indentation from content preserving the relative indentation within the content.
+ * @param content The content to remove indentation from
+ * @returns Content with common indentation removed
+ */
+module.exports = function removeIndentation( content ) {
+	// Remove unwanted indentation.
+	const lines = content.split( /\n/ );
+
+	// Skip empty lines when detecting indentation level
+	let indentationLine = 1;
+	while ( indentationLine < lines.length && !lines[ indentationLine ].trim() ) {
+		indentationLine++;
+	}
+
+	// Get the indentation of the first non-empty line, or empty string if no valid lines
+	const indentation = indentationLine < lines.length ? lines[ indentationLine ].match( /^\s*/ )[ 0 ] : '';
+
+	if ( !indentation ) {
+		return content.trim();
+	}
+
+	let pattern;
+
+	// When using spaces as indentation, some editors may mix them with tabs.
+	// In such case, let's try to remove tabs as well. 4 spaces are treat as a single tab character.
+	if ( indentation[ 0 ] === ' ' ) {
+		pattern = new RegExp( `^${ indentation }|${ '\\t'.repeat( Math.ceil( indentation.length / 4 ) ) }` );
+	} else {
+		pattern = new RegExp( `^${ indentation }` );
+	}
+
+	// Process each line to remove common indentation
+	content = lines.map( line => line.replace( pattern, '' ) ).join( '\n' );
+
+	// Remove first linebreak and last linebreak.
+	content = content.replace( /^\n/, '' );
+	content = content.replace( /\n$/, '' );
+
+	return content;
+};

package/scripts/utils/spritesheet-svg.js

@@ -0,0 +1,183 @@
+/**
+ * @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' );
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+const HexoManager = require( '../../src/hexo-manager' );
+
+/**
+ * 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
+	if ( elements.length === 0 ) {
+		return str;
+	}
+
+	// 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' );
+
+		if ( !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 );
+
+		collectSvgFileInfo( $element );
+		$element.remove();
+	} );
+
+	if ( svgFiles.size === 0 ) {
+		return str;
+	}
+
+	// Create spritesheet and get viewBox data
+	const { spritesheetElement, iconViewBoxes } = createSpritesheet( $, svgFiles );
+
+	// Add spritesheet to the beginning of the body
+	if ( $( 'body' ).length ) {
+		$( 'body' ).prepend( spritesheetElement );
+	}
+
+	// Set viewBox for original SVG elements
+	elements.each( function() {
+		const element = $( this );
+		const iconId = element.attr( 'data-spritesheet-id' );
+		const viewBox = iconViewBoxes.get( iconId );
+
+		if ( viewBox && this.tagName.toLowerCase() === 'svg' ) {
+			element.attr( 'viewBox', viewBox );
+		}
+	} );
+
+	$( '[data-spritesheet-svg]' ).removeAttr( 'data-spritesheet-svg' );
+	$( '[data-spritesheet-id]' ).removeAttr( 'data-spritesheet-id' );
+
+	return $.html();
+};
+
+/**
+ * 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 ) {
+	const symbols = [];
+	const iconViewBoxes = new Map();
+
+	for ( const [ iconId, svgPath ] of svgFiles.entries() ) {
+		const absolutePath = path.join( HexoManager.hexo.theme_dir, 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 $svg = SVG_CACHE.get( absolutePath ).clone();
+
+		// Create symbol element from SVG
+		const $symbol = $( '<symbol></symbol>' );
+		$symbol.attr( 'id', iconId );
+
+		// Copy viewBox and other relevant attributes
+		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 ( viewBoxValue ) {
+			$symbol.attr( '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() );
+			}
+		} );
+
+		symbols.push(
+			resetFillColor( $, $symbol )
+		);
+	}
+
+	// Create the spritesheet container
+	const $spritesheet = $( '<svg></svg>' );
+	$spritesheet.attr( {
+		'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 );
+	} );
+
+	return {
+		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.
+ */
+function resetFillColor( $, $svg ) {
+	// Replace all fill attributes with the specified color.
+	$svg.find( '[fill]' ).each( function() {
+		$( this ).attr( 'fill', 'currentColor' );
+	} );
+
+	// Also check the root SVG for fill attribute.
+	if ( $svg.attr( 'fill' ) ) {
+		$svg.attr( 'fill', 'currentColor' );
+	}
+
+	return $svg;
+}

package/scripts/utils/toc.js

@@ -0,0 +1,71 @@
+/**
+ * @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' );
+
+module.exports = function toc( data, options = {} ) {
+	const $ = cheerio.load( data, null, false );
+
+	let usedHeadings = [ 'h2', 'h3', 'h4', 'h5', 'h6' ];
+
+	if ( options.tocLimit >= 0 ) {
+		usedHeadings = usedHeadings.slice( 0, options.tocLimit );
+	}
+
+	usedHeadings = usedHeadings.join( ',' );
+
+	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 newItem = `<li><a class="a11y-focusable" href="#${ id }" title="${ text }">${ text }</a></li>`;
+
+		if ( tocLastLevels[ hLevel ] ) {
+			// If there already is a parent node for current heading level, append the new toc item there.
+			tocLastLevels[ hLevel ].append( newItem );
+		} 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>` );
+			} else {
+				$r( 'nav' ).append( `<ol>${ newItem }</ol>` );
+			}
+
+			// Assign new created <ol> element to the helper array.
+			tocLastLevels[ hLevel ] = $r( 'ol' ).last();
+		}
+
+		// 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.
+		clearLowerLevels( tocLastLevels, hLevel );
+	} );
+
+	return $r.html();
+};
+
+function clearLowerLevels( levels, current ) {
+	for ( let i = current + 1; i < levels.length; i++ ) {
+		levels[ i ] = 0;
+	}
+}

package/scripts/utils/transform-markdown-admonitions.js

@@ -0,0 +1,98 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const ParserCursor = require( './parser-cursor' );
+
+/**
+ * Transforms Github style admonitions in markdown to a rendered callouts.
+ *
+ * For example:
+ *
+ * > [!IMPORTANT]
+ * > This is an important message.
+ * > It should be highlighted.
+ *
+ * @param mapperFn - A function that takes an admonition object and returns a string.
+ * @param str - The string to transform.
+ * @returns The transformed string with admonitions replaced by the result of the mapper function.
+ */
+function transformMarkdownAdmonitions( mapperFn, str ) {
+	const cursor = new ParserCursor( str );
+	let acc = '';
+
+	for ( ; cursor.index < cursor.text.length; ) {
+		const ch = cursor.text[ cursor.index ];
+
+		if ( ch === '>' ) {
+			const maybeAdmonition = cursor.try( eatAdmonition );
+
+			if ( maybeAdmonition ) {
+				acc += mapperFn( maybeAdmonition );
+				continue;
+			}
+		}
+
+		acc += ch;
+		cursor.index++;
+	}
+
+	return acc;
+};
+
+/**
+ * Fast check if the string contains an admonition block.
+ */
+function fastCheckIfContainsAdmonition( str ) {
+	return str.includes( '> [!' ) && str.includes( ']' );
+}
+
+/**
+ * Eats an admonition block if it matches the expected pattern.
+ *
+ * @param cursor - The cursor to use for parsing.
+ * @returns An object representing the admonition type and content, or undefined (if not matched)
+ */
+function eatAdmonition( cursor ) {
+	if ( !cursor.eatTerminals( '> [!' ) ) {
+		return;
+	}
+
+	const type = cursor.eatUntilTerminal( ']' ).trim();
+
+	cursor.eatAllNextTerminals( ' \t\n ' );
+
+	const content = cursor.accumulateEaters( eatAdmonitionLine );
+
+	// Let's revert cursor back to the ending newline if it was consumed.
+	if ( content.length > 0 && cursor.text[ cursor.index - 1 ] === '\n' ) {
+		cursor.index--;
+	}
+
+	return {
+		type,
+		content
+	};
+}
+
+/**
+ * Eats a line of an admonition block.
+ *
+ * @param cursor - The cursor to use for parsing.
+ * @returns The content of the admonition line, or undefined if not matched.
+ */
+function eatAdmonitionLine( cursor ) {
+	cursor.eatIndent();
+
+	if ( !cursor.eatTerminal( '>' ) ) {
+		return;
+	}
+
+	return cursor.eatUntilEOL().trim();
+}
+
+exports.transformMarkdownAdmonitions = transformMarkdownAdmonitions;
+exports.fastCheckIfContainsAdmonition = fastCheckIfContainsAdmonition;

package/scripts/utils/uniq-by-last.js

@@ -0,0 +1,32 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Returns a new array with unique elements based on a specified property.
+ * When duplicates are found, the last occurrence is preferred.
+ *
+ * @param array - The array to process
+ * @param key - The property name to check for uniqueness or a function that extracts the value
+ * @returns A new array with unique elements
+ */
+module.exports = function uniqByLast( key, array ) {
+	const seen = new Map();
+
+	// Process from right to left to keep last occurrences
+	return array
+		.slice()
+		.reverse()
+		.filter( item => {
+			const value = typeof key === 'function' ? key( item ) : item[ key ];
+			if ( seen.has( value ) ) {
+				return false;
+			}
+			seen.set( value, true );
+			return true;
+		} )
+		.reverse();
+};