npm - umberto - Versions diffs - 8.0.0 → 8.0.2 - Mend

umberto 8.0.0 → 8.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,6 +1,32 @@
 Changelog
 =========
+## [8.0.2](https://github.com/cksource/umberto/compare/v8.0.1...v8.0.2) (July 31, 2025)
+### Bug fixes
+* Fixed an issue where code blocks appeared empty when displayed inside a `details` element in Chrome.
+* Changed from `overscroll-behavior: none` to `overscroll-behavior-y: none` on `<html>` and `<body>` elements to allow Mac trackpad swipe gestures for browser navigation.
+* Code blocks in API descriptions are no longer duplicated when there are multiple code blocks withing the same description.
+## [8.0.1](https://github.com/cksource/umberto/compare/v8.0.0...v8.0.1) (July 28, 2025)
+### Bug fixes
+* The performance of the building and the behavior of components have been improved. The most important changes are listed below:
+  * Improved the performance of the `validate-links` task by processing links in parallel across multiple CPU cores, instead of a single core.
+  * Enhanced the API filters behavior: now, when the `inherited` filter is unchecked while `internal` is selected, items tagged with both `inherited` and `internal` will be properly hidden from the results.
+  * Added the Lato font for improved typography and visual consistency.
+  * Restored the default selection color for content on the website to ensure a familiar and accessible user experience.
+  * Added a footer snippet for consistent branding and navigation across all pages.
+  * Improved the styling of `code` tags in API documentation for better readability and clarity.
+  * Added a new `sparkles` icon to the icon set.
+  * Fixed the project selection dropdown: after rebuilding, it now correctly displays all available projects instead of only one.
+  * Optimized the performance of the navigation tree building process, resulting in faster page loads and smoother navigation.
 ## [8.0.0](https://github.com/cksource/umberto/compare/v7.0.2...v8.0.0) (July 18, 2025)
 ### BREAKING CHANGES
@@ -37,24 +63,6 @@ Changelog
 * 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))
-## [7.0.0](https://github.com/cksource/umberto/compare/v6.1.2...v7.0.0) (2025-05-05)
-### BREAKING CHANGES
-* Rendering TypeScript-based API pages requires an input file generated by Typedoc in version `0.28.0` or later.
-### Features
-* Support for rendering TypeScript API pages based on output from `typedoc@0.28`. Closes [#1188](https://github.com/cksource/umberto/issues/1188). ([commit](https://github.com/cksource/umberto/commit/561f94c6b025a0f1dbcc01c0c0e70ee5eeae387e))
-## [6.1.2](https://github.com/cksource/umberto/compare/v6.1.1...v6.1.2) (2025-04-23)
-### Bug fixes
-* Umberto attempts to load the theme's favicons in case a project does not define its own, rather than generating links to non-existent resources. Closes [#1256](https://github.com/cksource/umberto/issues/1256). ([commit](https://github.com/cksource/umberto/commit/a6de17b195a67e78010773f420e54fa16b154378))
 ---
 To see all releases, visit the [release page](https://github.com/cksource/umberto/releases).

package/package.json CHANGED Viewed

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

package/scripts/filter/after-post-render/gloria/append-copy-heading-buttons.js CHANGED Viewed

@@ -6,8 +6,23 @@
 'use strict';
 const cheerio = require( 'cheerio' );
-const renderPugComponent = require( '../../../utils/pug-renderer/render-pug-component' );
-const hexoManager = require( '../../../../src/hexo-manager' );
+const createPrerenderPugTemplate = require( '../../../utils/pug-renderer/create-prerender-pug-template' );
+/**
+ * Renders the button using Pug template.
+ */
+const renderButton = createPrerenderPugTemplate( {
+	requires: [
+		'_components/svg/index',
+		'_components/icon/index',
+		'_components/tooltip-popover/index',
+		'_components/heading-link/index'
+	],
+	component: 'heading-link',
+	componentAttrs: {
+		mask: [ 'headingId' ]
+	}
+} );
 /**
  * Enforce priority 30 to run it after apply design doc classes filter.
@@ -34,8 +49,6 @@ hexo.extend.filter.register( 'after_post_render', page => {
 		// Create the copy button
 		const button = renderButton( {
-			hexo: hexoManager.hexo,
-			page,
 			headingId
 		} );
@@ -51,28 +64,6 @@ hexo.extend.filter.register( 'after_post_render', page => {
 	return page;
 }, 30 );
-/**
- * Renders the button using Pug template.
- */
-function renderButton( { hexo, page, headingId } ) {
-	return renderPugComponent( {
-		hexo,
-		requires: [
-			'_components/svg/index',
-			'_components/icon/index',
-			'_components/tooltip-popover/index',
-			'_components/heading-link/index'
-		],
-		mixinContextVars: {
-			page
-		},
-		component: 'heading-link',
-		componentAttrs: {
-			headingId
-		}
-	} );
-}
 /**
  * Removes all empty anchors that were created to hold the heading links buttons.
  */

package/scripts/filter/after-post-render/parseicontag.js CHANGED Viewed

@@ -12,4 +12,4 @@ const parseIconTag = require( '../../utils/parseicontag' );
  */
 hexo.extend.filter.register( 'after_post_render', page => {
 	return parseIconTag( page, hexo );
-} );
+}, 40 );

package/scripts/filter/after-render/gloria/inline-svg.js CHANGED Viewed

@@ -11,4 +11,4 @@ const inlineSvg = require( '../../../utils/inline-svg' );
  * Inlines SVG icons into HTML elements with data-inline-svg-image attribute.
  * The attribute value should contain the path to the SVG file.
  */
-hexo.extend.filter.register( 'after_render:html', inlineSvg );
+hexo.extend.filter.register( 'after_render:html', inlineSvg, 500 );

package/scripts/filter/after-render/gloria/spritesheet-svg.js CHANGED Viewed

@@ -11,4 +11,4 @@ const spritesheetSvg = require( '../../../utils/spritesheet-svg' );
  * Creates a spritesheet from SVG files referenced by data-spritesheet-svg attributes
  * and injects it at the beginning of the body with display: none.
  */
-hexo.extend.filter.register( 'after_render:html', spritesheetSvg );
+hexo.extend.filter.register( 'after_render:html', spritesheetSvg, 499 );

package/scripts/filter/before-post-render/gloria/add-breadcrumbs-data-to-page.js CHANGED Viewed

@@ -12,6 +12,12 @@ const concatUrlParts = require( '../../../utils/concat-url-parts' );
 const relative_url = require( 'hexo/dist/plugins/helper/relative_url' ); // eslint-disable-line camelcase
 const dropInitSlash = require( '../../../utils/drop-init-slash' );
+/**
+ * `hexo.model` calls are REALLY slow, so we cache them. It takes approx
+ * 10s to load all of these pages.
+ */
+let PAGES;
 /**
  * Adds breadcrumbs data to the page by finding links to parent categories.
  *
@@ -43,7 +49,8 @@ hexo.extend.filter.register( 'before_post_render', page => {
 	const { categoryIds, config } = projectGlobals;
 	const basePath = hexo.projectGlobals[ page.projectName ].BASE_PATH;
-	const pages = hexo.model( 'Page' ).toArray();
+	PAGES ||= hexo.model( 'Page' ).toArray();
 	// Get all categories and groups from the project globals.
 	const categoriesBreadcrumbs = getAllParentCategories( categoryIds, page.category )
@@ -70,7 +77,7 @@ hexo.extend.filter.register( 'before_post_render', page => {
 			// is placed within directory of another category but is mapped
 			// to the different category in `umberto.json`.
 			const path = ( () => {
-				const overviewPage = pages.find(
+				const overviewPage = PAGES.find(
 					nestedPage =>
 						nestedPage.category === category.id &&
 						isOverviewPage( nestedPage )

package/scripts/filter/before-post-render/gloria/prerender-xml-pug-components.js CHANGED Viewed

@@ -143,6 +143,19 @@ const PATTERN_ELEMENTS = [
 		]
 	},
+	// Labels
+	{
+		pattern: /(?:ck:)?snippet-footer$/,
+		mixinName: 'snippet-footer',
+		allowMarkdownContent: true,
+		requires: [
+			'_components/svg/index',
+			'_components/icon/index',
+			'_components/icon-message/index',
+			'_components/snippet-footer/index'
+		]
+	},
 	// Code block
 	{
 		pattern: 'ck:code-block',

package/scripts/filter/before-post-render/gloria/render-post-render-pug-components.js CHANGED Viewed

@@ -25,13 +25,19 @@ const POST_RENDER_COMPONENTS = [
 					'_components/skeleton/index',
 					'_components/code-block/index'
 				],
-				skipCacheIf: ( { code } ) => code?.split( '\n' ).length > 1,
+				createCacheKey: ( _, { copyable, language, skeletonLines } ) => {
+					const linesCacheKey = skeletonLines < 6 ?
+						skeletonLines :
+						Math.floor( skeletonLines / 5 ) + 100;
+					return `code-block-${ language }-${ copyable }-${ linesCacheKey }`;
+				},
 				component: 'code-block',
 				componentAttrs: {
 					static: {
 						copyable: true
 					},
-					dynamic: [ 'copyable', 'language' ],
+					dynamic: [ 'copyable', 'language', 'skeletonLines' ],
 					mask: [ 'code' ]
 				}
 			} );
@@ -45,10 +51,12 @@ const POST_RENDER_COMPONENTS = [
 				// Get the language from the class (e.g., "language-js" -> "js")
 				const language = $code.attr( 'class' ).replace( 'doc', '' ).trim();
+				const code = $code.html();
 				return template( {
-					code: $code.html(),
-					language
+					code,
+					language,
+					skeletonLines: code.trim().split( '\n' ).length
 				} );
 			};
 		} )()
@@ -69,7 +77,7 @@ hexo.extend.filter.register( 'after_post_render', page => {
 				return;
 			}
-			$ = $ || cheerio.load( page.content );
+			$ = $ || cheerio.load( page.content, null, false );
 			$( component.selector ).each( ( i, element ) => {
 				const $element = $( element );
@@ -91,4 +99,4 @@ hexo.extend.filter.register( 'after_post_render', page => {
 	}
 	return page;
-} );
+}, 100 );

package/scripts/helper/u-extract-and-cache-title.js ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * @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 CACHED_TITLES = new Map();
+hexo.extend.helper.register( 'uExtractAndCacheTitle', ( cacheKey, data ) => {
+	if ( !cacheKey ) {
+		throw new Error( 'Cache key is required for uExtractAndCacheTitle helper.' );
+	}
+	if ( CACHED_TITLES.has( cacheKey ) ) {
+		return CACHED_TITLES.get( cacheKey );
+	}
+	const $ = cheerio.load( data, null, false );
+	const title = $( 'h1:not( .live-snippet h1 )' ).first();
+	const formattedTitle = (
+		title
+			.children()
+			.remove()
+			.end()
+			.text()
+			.trim()
+			.replace( /</g, '&lt;' )
+			.replace( />/g, '&gt;' )
+	);
+	CACHED_TITLES.set( cacheKey, formattedTitle );
+	return formattedTitle;
+} );

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

@@ -63,15 +63,22 @@ const renderPugComponent = require( './render-pug-component' );
  * // 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, ...renderAttrs } ) {
+module.exports = function createPrerenderPugTemplate(
+	{
+		componentAttrs,
+		skipCacheIf,
+		createCacheKey = createDefaultCacheKey,
+		...renderAttrs
+	}
+) {
 	const cacheStorage = new Map();
 	const maskAttrsMap = assignMaskAttrsIds( componentAttrs.mask || [] );
-	const allKnownAttributes = [
+	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.
@@ -130,7 +137,13 @@ module.exports = function createPrerenderPugTemplate( { componentAttrs, skipCach
  * Checks if the provided component attributes contain any unknown attributes.
  */
 function hasUnknownAttributes( knownAttributes, componentAttrs ) {
-	return Object.keys( componentAttrs ).some( attr => !knownAttributes.includes( attr ) );
+	for ( const attr in componentAttrs ) {
+		if ( !knownAttributes.has( attr ) ) {
+			return true;
+		}
+	}
+	return false;
 }
 /**
@@ -140,7 +153,7 @@ function hasUnknownAttributes( knownAttributes, componentAttrs ) {
  * @param componentAttrs An object containing component attributes and their values.
  * @returns The generated cache key.
  */
-function createCacheKey( cacheByAttributes, componentAttrs ) {
+function createDefaultCacheKey( cacheByAttributes, componentAttrs ) {
 	if ( !cacheByAttributes?.length ) {
 		return 'default';
 	}

package/scripts/utils/random-id.js CHANGED Viewed

@@ -28,6 +28,13 @@ function randomId( prefix, maskable = true ) {
 	return id;
 };
+/**
+ * Checks if the given ID is a masked ID.
+ */
+function isMaskedID( id ) {
+	return id.startsWith( 'gen-' );
+}
 /**
  * Regenerates random IDs in a string.
  *
@@ -62,6 +69,7 @@ function regenerateRandomIds( str ) {
 }
 module.exports = {
+	isMaskedID,
 	randomId,
 	regenerateRandomIds
 };

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

@@ -387,28 +387,29 @@ module.exports = class DescriptionParser {
 		const theme = options.theme;
 		if ( theme === 'gloria' ) {
-			const $code = $( 'pre code' );
+			$( 'pre' ).each( function() {
+				const $code = $( this ).find( 'code' );
-			if ( !$code.length ) {
-				return null;
-			}
+				if ( !$code || !$code.length ) {
+					return;
+				}
-			// 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() :
-				null;
+				// 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() :
+					null;
-			// Get the code content
-			const code = $code.html();
+				// Get the code content
+				const code = $code.html();
-			// Use the render-pug-component utility
-			const html = renderCodeBlockPug( {
-				language,
-				code
-			} );
+				// Use the render-pug-component utility
+				const html = renderCodeBlockPug( {
+					language,
+					code
+				} );
-			$( this ).html( html );
-			$( 'pre' ).replaceWith( html );
+				$( this ).replaceWith( html );
+			} );
 		} else {
 			$( 'pre[class~="source"]' ).each( function() {
 				let code = $( this ).html();

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

@@ -25,6 +25,7 @@ const umbertoVersion = require( '../../../package.json' ).version;
  * @param {Array} extraStylePaths Paths to extra external css.
  * @param {Array} extraScriptsPaths Paths to extra external js.
  * @param {Boolean} disableSearch Extra flag for disabling docsearch if needed.
+ * @param {Array} quickNavigationProjects Projects to display in the quick navigation dropdown.
  * @param {Boolean} navigationShowEmptyCategories If set on true, empty categories will be displayed.
  * @param {Object} og Open Graph config.
  */
@@ -42,6 +43,7 @@ module.exports = ( ctx, {
 	extraScriptsPaths,
 	disableSearch,
 	og,
+	quickNavigationProjects,
 	navigationShowEmptyCategories
 } = {} ) => {
 	ctx.extend.filter.register( 'template_locals', locals => {
@@ -84,6 +86,7 @@ module.exports = ( ctx, {
 			locals.projectsData = [];
 		}
+		locals.quickNavigationProjects = quickNavigationProjects;
 		locals.projectsData.push( {
 			name: projectName,
 			slug: projectSlug,

package/src/tasks/build-api-docs.js CHANGED Viewed

@@ -64,7 +64,7 @@ module.exports = async config => {
 		}
 	);
-	console.log( `Building API docs of ${ projectConfig.name }...` );
+	console.log( `Building API docs of ${ projectConfig.name } ...` );
 	console.time( `Built API docs of ${ projectConfig.name } in` );
 	const buildInfo = await apiBuilder.buildApi();
 	console.timeEnd( `Built API docs of ${ projectConfig.name } in` );

package/src/tasks/build-documentation.js CHANGED Viewed

@@ -151,13 +151,18 @@ module.exports = options => {
 				additionalDocumentation: mainConfig.additionalDocumentation,
 				canonicalUrlBeginning: mainConfig.canonicalUrlBeginning,
 				macrosVariables: mainConfig.variables,
+				quickNavigationProjects: mainConfig.quickNavigationProjects || [
+					{ name: 'CKEditor 5', slug: 'ckeditor5' },
+					{ name: 'Cloud Services', slug: 'cs' },
+					{ name: 'CKBox', slug: 'ckbox' }
+				],
 				guides,
 				skipGuides
 			} );
 		} )
 		.then( () => hexoManager.generate( {
 			watch,
-			concurrency: 50
+			concurrency: 80
 		} ) )
 		.then( () => buildSnippets( hexoManager.hexo.projectGlobals ) )
 		.then( () => copyProjectIcons( hexoManager.hexo.projectGlobals, hexoManager.getPublicDir() ) )
@@ -276,7 +281,8 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 				feedbackWidget: options.feedbackWidget,
 				og: options.og,
 				canonicalUrlBeginning: options.canonicalUrlBeginning,
-				macrosVariables: options.macrosVariables
+				macrosVariables: options.macrosVariables,
+				quickNavigationProjects: options.quickNavigationProjects
 			} )
 		);
 	}
@@ -297,7 +303,8 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			feedbackWidget: options.feedbackWidget,
 			og: options.og,
 			canonicalUrlBeginning: options.canonicalUrlBeginning,
-			macrosVariables: options.macrosVariables
+			macrosVariables: options.macrosVariables,
+			quickNavigationProjects: options.quickNavigationProjects
 		} ) );
 	}
@@ -347,6 +354,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			googletagmanager: options.googletagmanager,
 			googleanalytics: options.googleanalytics,
 			promobar: options.promobar,
+			quickNavigationProjects: options.quickNavigationProjects,
 			vwo: options.vwo,
 			feedbackWidget: options.feedbackWidget,
 			extraStylePaths: extraStyles,
@@ -439,6 +447,7 @@ async function buildApis( projectConfigs, options = {} ) {
 			macrosVariables: options.macrosVariables,
 			templateLocals: {
 				projectsData: basicProjectsData,
+				quickNavigationProjects: options.quickNavigationProjects,
 				extraStylePaths: options.extraStyles,
 				extraScriptsPaths: options.extraScripts,
 				sitemap: config.sitemap || options.sitemap,
@@ -535,6 +544,7 @@ function buildSdks( projectConfigs, options = {} ) {
 				googleoptimize: options.googleoptimize,
 				googletagmanager: options.googletagmanager,
 				googleanalytics: options.googleanalytics,
+				quickNavigationProjects: options.quickNavigationProjects,
 				promobar: options.promobar,
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,