umberto 7.0.2 → 8.0.1

package/scripts/utils/parselinks.js

@@ -22,7 +22,7 @@ const logCrossProjectReference = require( './logcrossprojectreference' );
  * @param {Object} hexo
  * @return {Boolean}
  */
-module.exports = function parseLinks( page, hexo ) {
+function parseLinks( page, hexo ) {
 	const isSilentError = hexo.projectGlobals.common._disabledFilters.has( parseLinks.name );
 	const relativeUrlHelper = hexo.extend.helper.store.relative_url;
 
@@ -50,7 +50,7 @@ module.exports = function parseLinks( page, hexo ) {
  * @param {Function} options.relativeUrlHelper
  * @param {Boolean} options.isSilentError
  */
-function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
+function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError }, onlyHref = false ) {
 	const linkMatchResult = str.match( /^{((?:@linkapi|@link)[\s\S]+)}$/ );
 
 	if ( !linkMatchResult ) {
@@ -174,6 +174,10 @@ function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 		linkText = `event-${ targetDoclet.name }`;
 	}
 
+	if ( onlyHref ) {
+		return href;
+	}
+
 	return getOutputLink( href, linkText, !!linkContentMatchResult[ 3 ] );
 }
 
@@ -231,7 +235,7 @@ function getOutputLink( href, description, isCustomDescription ) {
  * @param {Function} options.relativeUrlHelper
  * @param {Boolean} options.isSilentError
  */
-function linkToSdk( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
+function linkToSdk( str, data, hexo, { relativeUrlHelper, isSilentError }, onlyHref = false ) {
 	const regExp = /(?:@linksdk|@linkexample) (?:@(\w+) )?(\w+)(?:\.html)?(#\S+)? ([^}]+)/;
 	const match = regExp.exec( str );
 
@@ -256,8 +260,13 @@ function linkToSdk( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 	const sdkFileHash = match[ 3 ] || '';
 	const sdkLinkName = match[ 4 ];
 	const link = relativeUrlHelper( data.path, upath.join( basePath, sdkSlug, sdkFileName ) );
+	const finalHref = `${ link }.html${ sdkFileHash }`;
+
+	if ( onlyHref ) {
+		return finalHref;
+	}
 
-	return `<a href="${ link }.html${ sdkFileHash }">${ sdkLinkName }</a>`;
+	return `<a href="${ finalHref }">${ sdkLinkName }</a>`;
 }
 
 /**
@@ -268,7 +277,7 @@ function linkToSdk( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
  * @param {Function} options.relativeUrlHelper
  * @param {Boolean} options.isSilentError
  */
-function linkToGuide( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
+function linkToGuide( str, data, hexo, { relativeUrlHelper, isSilentError }, onlyHref = false ) {
 	const rgxp = /@link(?:\s+@(\w+))?\s+([^}\s]+)\s*([^}]*)}/;
 	const match = rgxp.exec( str );
 
@@ -328,8 +337,13 @@ function linkToGuide( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 	}
 
 	const href = relativeUrlHelper( data.path, targetPath );
+	const finalHref = `${ href }${ hash }`;
 
-	return `<a href=${ href }${ hash }>${ linkText }</a>`;
+	if ( onlyHref ) {
+		return finalHref;
+	}
+
+	return `<a href=${ finalHref }>${ linkText }</a>`;
 }
 
 /**
@@ -371,3 +385,10 @@ function getSlug( config, name ) {
 
 	return null;
 }
+
+module.exports = {
+	parseLinks,
+	linkToApi,
+	linkToSdk,
+	linkToGuide
+};

package/scripts/utils/parser-cursor.js

@@ -0,0 +1,280 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * A cursor class that enables creating a left recursion recursive descent parser.
+ * It maintains position state and provides backtracking capabilities for parsing operations.
+ */
+class ParserCursor {
+	#_stack = [];
+
+	/**
+	 * Creates a new cursor instance for parsing text.
+	 *
+	 * @param text - The text to parse.
+	 * @param [index=0] - The initial position in the text.
+	 */
+	constructor( text, index = 0 ) {
+		this.index = index;
+		this.text = text;
+	}
+
+	/**
+	 * Executes a callback with automatic cursor position management.
+	 * If the callback returns undefined, the cursor position is restored to the state before the call.
+	 * This enables backtracking in the parser.
+	 *
+	 * @param callback - The callback function to execute.
+	 * @returns The result of the callback function.
+	 */
+	try( callback ) {
+		this.#push();
+
+		const result = callback( this );
+
+		if ( result === undefined ) {
+			this.index = this.#pop();
+		} else {
+			this.#pop( false );
+		}
+
+		return result;
+	}
+
+	/**
+	 * Attempts to consume a single terminal character at the current position.
+	 *
+	 * @param ch - The character to match and consume.
+	 * @returns True if the character was consumed, false otherwise.
+	 */
+	eatTerminal( ch ) {
+		if ( this.text[ this.index ] !== ch ) {
+			return false;
+		}
+
+		this.index++;
+		return true;
+	}
+
+	/**
+	 * Attempts to consume a sequence of terminal characters.
+	 * All characters must match in order for the operation to succeed.
+	 *
+	 * @param chars - The sequence of characters to match and consume.
+	 * @returns True if all characters were consumed, false otherwise.
+	 */
+	eatTerminals( chars ) {
+		this.#push();
+
+		for ( const ch of chars ) {
+			if ( !this.eatTerminal( ch ) ) {
+				this.#pop();
+				return false;
+			}
+		}
+
+		this.#pop( false );
+		return true;
+	}
+
+	/**
+	 * Consumes all terminal characters from the current position until a non-terminal character is encountered.
+	 *
+	 * @param chars - The characters to consume. If not provided, defaults to whitespace characters.
+	 */
+	eatAllNextTerminals( chars ) {
+		while ( this.index < this.text.length && chars.includes( this.text[ this.index ] ) ) {
+			this.index++;
+		}
+	}
+
+	/**
+	 * Consumes all whitespace characters (spaces and tabs) from the current position.
+	 */
+	eatIndent() {
+		this.eatAllNextTerminals( ' \t' );
+	}
+
+	/**
+	 * Consumes characters from the current position until a character matches the provided matcher function.
+	 * It consumes terminal character but does not include it in the result.
+	 *
+	 * @param matcher - A function that takes a character and returns true if it matches the condition to stop consuming.
+	 */
+	eatAllNextUntil( matcher ) {
+		let acc = '';
+
+		while ( this.index < this.text.length ) {
+			const ch = this.text[ this.index++ ];
+
+			if ( matcher( ch ) ) {
+				return acc;
+			}
+
+			acc += ch;
+		}
+
+		return acc;
+	}
+
+	/**
+	 * Consumes characters from the current position until a specific character is encountered.
+	 * It consumes terminal character but does not include it in the result.
+	 *
+	 * @param char - The character to stop consuming at.
+	 * @returns The consumed characters up to the specified character.
+	 */
+	eatUntilTerminal( char ) {
+		return this.eatAllNextUntil( c => c === char );
+	}
+
+	/**
+	 * Consumes characters from the current position until a newline character is encountered.
+	 * It consumes terminal character but does not include it in the result.
+	 */
+	eatUntilEOL() {
+		return this.eatAllNextUntil( c => c === '\n' );
+	}
+
+	/**
+	 * Attempts to consume a quoted string (single or double quotes).
+	 * Returns the content between the quotes without the quote characters.
+	 * Supports escaped quotes using backslash.
+	 *
+	 * @returns The quoted content or null if no valid quote was found.
+	 */
+	eatQuote() {
+		const quoteChar = this.text[ this.index ];
+
+		let started = false;
+		let acc = '';
+		let escaped = false;
+
+		this.#push();
+
+		for ( ; this.index < this.text.length; ++this.index ) {
+			const ch = this.text[ this.index ];
+
+			if ( escaped ) {
+				// Handle escaped characters
+				if ( ch === quoteChar || ch === '\\' ) {
+					acc += ch;
+				} else {
+					acc += '\\' + ch;
+				}
+
+				escaped = false;
+			} else if ( ch === '\\' ) {
+				escaped = true;
+			} else if ( ch !== quoteChar ) {
+				acc += ch;
+			} else if ( !started ) {
+				started = true;
+			} else {
+				// eat the closing quote
+				this.index++;
+				break;
+			}
+		}
+
+		if ( started ) {
+			this.#pop( false );
+			return acc;
+		}
+
+		this.#pop();
+		return null;
+	}
+
+	/**
+	 * Consumes a word (alphanumeric characters, underscore, and optionally other allowed characters).
+	 *
+	 * @param [whitelist=':-'] - Additional characters to allow in the word.
+	 * @returns The consumed word, or empty string if no word was found.
+	 */
+	eatWord( whitelist = ':-' ) {
+		let acc = '';
+
+		this.#push();
+
+		for ( ; this.index < this.text.length; ++this.index ) {
+			const ch = this.text[ this.index ];
+
+			if ( !isWordChar( ch ) && !whitelist.includes( ch ) ) {
+				break;
+			}
+
+			acc += ch;
+		}
+
+		this.#pop( !acc );
+
+		return acc;
+	}
+
+	/**
+	 * Attempts to consume Nth productions until a production is not matched.
+	 */
+	accumulateEaters( production ) {
+		const results = [];
+
+		for ( let watchdog = 0; watchdog < 1000; watchdog++ ) {
+			const result = this.try( production );
+
+			if ( result !== undefined ) {
+				results.push( result );
+			} else {
+				break;
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Saves the current cursor position to the internal stack.
+	 * This enables backtracking by restoring to this position later.
+	 */
+	#push() {
+		this.#_stack.push( this.index );
+	}
+
+	/**
+	 * Removes and optionally restores the last saved cursor position from the stack.
+	 *
+	 * @param [assign=true] - If true, restores the cursor to the popped position.
+	 * @returns The popped position value.
+	 */
+	#pop( assign = true ) {
+		const value = this.#_stack.pop();
+
+		if ( assign ) {
+			this.index = value;
+		}
+
+		return value;
+	}
+};
+
+/**
+ * Checks if a character is a word character (alphanumeric or underscore).
+ *
+ * @param c - The character to check.
+ * @returns True if the character is a word character.
+ */
+function isWordChar( c ) {
+	const code = c.charCodeAt( 0 );
+
+	return (
+		( code >= 65 && code <= 90 ) || // A-Z
+		( code >= 97 && code <= 122 ) || // a-z
+		( code >= 48 && code <= 57 ) || // 0-9
+		code === 95 // _
+	);
+}
+
+module.exports = ParserCursor;

package/scripts/utils/pipe.js

@@ -0,0 +1,17 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * Applies a series of functions to an input value, passing the result of each function
+ * as the input to the next function.
+ *
+ * @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 ) {
+	return value => fns.reduce( ( acc, fn ) => fn( acc ), value );
+};

package/scripts/utils/pug-renderer/create-prerender-pug-template.js

@@ -0,0 +1,185 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { randomId, regenerateRandomIds } = require( '../random-id' );
+const renderPugComponent = require( './render-pug-component' );
+
+/**
+ * Creates a template function for a Pug component with a built-in caching mechanism.
+ *
+ * This function is useful for optimizing the rendering of components that are used multiple times
+ * with minor changes in attributes. It divides attributes into three categories: `static`, `dynamic`, and `mask`,
+ * to efficiently manage caching.
+ *
+ * - `static`: Attributes that are the same for all instances of the component.
+ *   They are passed to the Pug component during the first render.
+ *
+ * - `dynamic`: Attributes whose values can change and affect the component's appearance or structure.
+ *   A cache key is generated based on the combination of these attribute values.
+ *   A new version of the component is rendered and cached for each unique combination of these attribute values.
+ *
+ * - `mask`: Attributes whose values are unique for each call and should not be part of the cached HTML.
+ *   Instead, unique identifiers (masks) are inserted into the cached template, which are replaced
+ *   with the actual values after retrieving the template from the cache. This is ideal for content
+ *   such as code in a code block.
+ *
+ * @example
+ * const createPrerenderPugTemplate = require( './create-prerender-pug-template' );
+ *
+ * // Creates a template for the 'code-block' component.
+ * const codeBlockTemplate = createPrerenderPugTemplate( {
+ *   // Attributes for `renderPugComponent`.
+ *   includes: [ '_components/code-block/index' ],
+ *   component: 'code-block',
+ *
+ *   // Attributes for the component itself.
+ *   componentAttrs: {
+ *     // Static attributes are the same for every render.
+ *     static: {
+ *       copyable: true
+ *     },
+ *     // Dynamic attributes are used for caching.
+ *     // A new version of the component will be rendered and cached
+ *     // for each unique combination of these attribute values.
+ *     dynamic: [ 'language' ],
+ *     // Masked attributes are replaced after rendering (even from the cache).
+ *     // They are used for unique content that should not be cached.
+ *     mask: [ 'code' ]
+ *   }
+ * } );
+ *
+ * // Using the template.
+ * // The first call will render the component for the 'javascript' language and cache it.
+ * const html1 = codeBlockTemplate( { language: 'javascript', code: 'console.log( "Hello" );' } );
+ *
+ * // This call will use the cached version for 'javascript'.
+ * // Only 'code' will be replaced.
+ * const html2 = codeBlockTemplate( { language: 'javascript', code: 'console.log( "World" );' } );
+ *
+ * // This will render a new version for 'html' and cache it.
+ * const html3 = codeBlockTemplate( { language: 'html', code: '<h1>Hello</h1>' } );
+ */
+module.exports = function createPrerenderPugTemplate(
+	{
+		componentAttrs,
+		skipCacheIf,
+		createCacheKey = createDefaultCacheKey,
+		...renderAttrs
+	}
+) {
+	const cacheStorage = new Map();
+	const maskAttrsMap = assignMaskAttrsIds( componentAttrs.mask || [] );
+
+	const allKnownAttributes = new Set( [
+		...componentAttrs.dynamic || [],
+		...Object.keys( componentAttrs.static || {} ),
+		...componentAttrs.mask || []
+	] );
+
+	return dynamicAttrs => {
+		// Check if we should skip caching based on the provided condition.
+		const skipCache = skipCacheIf?.( dynamicAttrs );
+
+		if ( skipCache ) {
+			return renderPugComponent( {
+				...renderAttrs,
+				componentAttrs: {
+					...componentAttrs.static,
+					...dynamicAttrs
+				}
+			} );
+		}
+
+		// Check if component is already pre-rendered, if so, return cached HTML.
+		const _hasUnknownAttributes = hasUnknownAttributes( allKnownAttributes, dynamicAttrs );
+		const cacheKey = createCacheKey( componentAttrs.dynamic, dynamicAttrs );
+
+		let renderedHtml;
+
+		if ( !_hasUnknownAttributes && cacheStorage.has( cacheKey ) ) {
+			renderedHtml = cacheStorage.get( cacheKey );
+		} else {
+			renderedHtml = renderPugComponent( {
+				...renderAttrs,
+				componentAttrs: {
+					...componentAttrs.static,
+					...dynamicAttrs,
+					...maskAttrsMap
+				}
+			} );
+
+			if ( !_hasUnknownAttributes ) {
+				cacheStorage.set( cacheKey, renderedHtml );
+			}
+		}
+
+		// Regenerate random IDs in the rendered HTML to ensure uniqueness.
+		renderedHtml = regenerateRandomIds( renderedHtml );
+
+		for ( const maskKey in maskAttrsMap ) {
+			const dynamicValue = dynamicAttrs[ maskKey ] || '';
+
+			renderedHtml = renderedHtml.replace(
+				maskAttrsMap[ maskKey ],
+				dynamicValue
+			);
+		}
+
+		return renderedHtml;
+	};
+};
+
+/**
+ * Checks if the provided component attributes contain any unknown attributes.
+ */
+function hasUnknownAttributes( knownAttributes, componentAttrs ) {
+	for ( const attr in componentAttrs ) {
+		if ( !knownAttributes.has( attr ) ) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Creates a cache key based on the specified attributes and their values.
+ *
+ * @param cacheByAttributes An array of attribute names to be included in the cache key.
+ * @param componentAttrs An object containing component attributes and their values.
+ * @returns The generated cache key.
+ */
+function createDefaultCacheKey( cacheByAttributes, componentAttrs ) {
+	if ( !cacheByAttributes?.length ) {
+		return 'default';
+	}
+
+	let acc = '';
+
+	for ( const attr of cacheByAttributes ) {
+		acc += `${ attr }-${ componentAttrs[ attr ] || 'undefined' }-`;
+	}
+
+	return acc;
+}
+
+/**
+ * Creates an object that maps mask attribute names to unique random IDs.
+ *
+ * @param maskAttributes An array of attribute names that should be masked.
+ * @returns An object where keys are attribute names and values are unique mask IDs.
+ */
+function assignMaskAttrsIds( maskAttributes ) {
+	return maskAttributes.reduce(
+		( acc, attr ) => {
+			acc[ attr ] = randomId( 'mask', false );
+
+			return acc;
+		},
+		Object.create( {} )
+	);
+}

package/scripts/utils/pug-renderer/render-pug-component.js

@@ -0,0 +1,73 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const path = require( 'path' );
+const hexoManager = require( '../../../src/hexo-manager' );
+
+/**
+ * Renders a Pug component with specified includes and parameters.
+ *
+ * @param options - The rendering options.
+ * @param options.hexo - The Hexo instance.
+ * @param options.mixinContextVars - Context variables to be passed to the Pug mixin.
+ * @param [options.requires=[]] - Array of Pug includes to be added at the top of the template.
+ * @param options.component - The name of the component to render (without the + prefix).
+ * @param [options.componentAttrs={}] - Attributes to pass to the component.
+ * @param [options.basePath] - Base path for the component. Defaults to theme components directory.
+ * @returns The rendered HTML.
+ */
+module.exports = function renderPugComponent(
+	{
+		hexo,
+		mixinContextVars = {},
+		requires = [],
+		component,
+		componentAttrs = {},
+		basePath
+	}
+) {
+	const { children, ...restComponentAttrs } = componentAttrs || {};
+
+	// Default base path is the components directory in the theme
+	// Handle case where hexo.theme_dir might be undefined
+	const resolvedHexo = hexo || hexoManager.hexo;
+	const themeDir = resolvedHexo && resolvedHexo.theme_dir || path.join( __dirname, '../../themes/umberto' );
+	const componentsPath = basePath || path.join( themeDir, 'layout', 'gloria', '_components' );
+
+	// Prepare includes statements
+	const includeStatements = requires.map( include => `include ${ include }` );
+
+	// Prepare the component call with its attributes
+	const componentCall = `+${ component }(${ JSON.stringify( restComponentAttrs ) })`;
+
+	// Complete content to be rendered
+	const content = [
+		...includeStatements,
+		componentCall,
+		children
+	]
+		.filter( Boolean )
+		.join( '\n' );
+
+	// Prepare locals for rendering
+	const locals = Object.assign(
+		{},
+		resolvedHexo.locals.toObject(),
+		resolvedHexo.extend.helper.list(),
+		{
+			...mixinContextVars,
+			config: resolvedHexo.config
+		}
+	);
+
+	// Render and return the component
+	return resolvedHexo.render.renderSync( {
+		text: content,
+		engine: 'pug',
+		path: componentsPath
+	}, locals );
+};