umberto 8.0.0 → 8.0.1

package/CHANGELOG.md

@@ -1,6 +1,23 @@
 Changelog
 =========
 
+## [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
@@ -48,13 +65,6 @@ Changelog
 
 * 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

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

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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/hexo/filter/project-locals.js

@@ -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

@@ -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

@@ -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,