umberto 8.4.0 → 9.1.0

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 Changelog
 =========
 
+## [9.1.0](https://github.com/cksource/umberto/compare/v9.0.0...v9.1.0) (November 24, 2025)
+
+### Features
+
+* Introduced support for [Sentry](https://sentry.io/welcome/) in the generated documentation.
+
+  Umberto configuration can now specify the `sentry` key that allows loading the Sentry SDK on production hosts: https://ckeditor.com/docs and https://ckeditor5.github.io/docs/nightly.
+
+### Other changes
+
+* Improve performance of `api-builder` and `validate-links` scripts.
+* Migrate from `cheerio` to `htmlparser2` and friends.
+
+
+## [9.0.0](https://github.com/cksource/umberto/compare/v8.4.0...v9.0.0) (November 13, 2025)
+
+### BREAKING CHANGES
+
+* Updated the required version of Node.js to **v24.11**.
+
+
 ## [8.4.0](https://github.com/cksource/umberto/compare/v8.3.5...v8.4.0) (October 30, 2025)
 
 ### Features
@@ -29,22 +50,6 @@ Changelog
 
 * Bump dependencies (including `hexo` to version `8.0.0`).
 
-
-## [8.3.3](https://github.com/cksource/umberto/compare/v8.3.2...v8.3.3) (October 15, 2025)
-
-### Bug fixes
-
-* Link validator should not fail on links containing the word "latest", if they are not part of a version number.
-* Fixed links being unstyled in Kapa.ai answers.
-* Fix broken page sidebar layout on `959px` resolution.
-
-
-## [8.3.2](https://github.com/cksource/umberto/compare/v8.3.1...v8.3.2) (September 16, 2025)
-
-### Other changes
-
-* Update to TypeScript 5.3.
-
 ---
 
 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.4.0",
+  "version": "9.1.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -19,7 +19,10 @@
     "@ckeditor/jsdoc-plugins": "^43.0.0",
     "@minify-html/node": "^0.17.1",
     "babel-loader": "^10.0.0",
-    "cheerio": "^1.0.0",
+    "css-select": "^6.0.0",
+    "dom-serializer": "^2.0.0",
+    "domhandler": "^5.0.3",
+    "domutils": "^3.2.2",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^11.0.0",
     "fuse.js": "^7.1.0",
@@ -55,9 +58,7 @@
     "webpack": "^5.94.0"
   },
   "engines": {
-    "node": ">=22.0.0",
-    "pnpm": ">=10.14.0",
-    "yarn": "\n\n┌─────────────────────────┐\n│  Hey, we use pnpm now!  │\n└─────────────────────────┘\n\n"
+    "node": ">=24.11.0"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "MIT",
@@ -73,6 +74,6 @@
     ]
   },
   "hexo": {
-    "version": "8.0.0"
+    "version": "8.1.1"
   }
-}
+}

package/scripts/filter/after-post-render/fix-code-samples.js

@@ -5,7 +5,10 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll, selectOne } = require( 'css-select' );
+const { hasAttrib, getChildren } = require( 'domutils' );
 
 const regexp = /(?<=>)utf8_encoded_content:([0-9,]+)(?=<\/code><\/pre>)/g;
 const textDecoder = new TextDecoder();
@@ -23,28 +26,89 @@ hexo.extend.filter.register( 'after_post_render', page => {
 		} );
 	}
 
-	const $ = cheerio.load( page.content, null, false );
+	// Only bother scanning/transforming <pre> blocks if they are present.
+	if ( page.content.indexOf( '<pre' ) === -1 ) {
+		return page;
+	}
 
-	// This is an attempt to automatically discover code blocks of HTML and add 'html' class if needed.
-	// It is needed for triple backtick ``` codeblocks in markdown which contain HTML but don't use ```html notation.
-	if ( page.content.indexOf( '<pre' ) !== -1 ) {
-		$( 'pre' ).each( function() {
-			const codeEl = $( this ).find( 'code' );
+	const doc = parseDocument( page.content );
+	const preBlocks = selectAll( 'pre', doc );
 
-			if ( codeEl.is( '.html,.js,.php,.css,.java' ) ) {
-				return true;
-			}
+	for ( const pre of preBlocks ) {
+		const code = selectOne( 'code', pre );
 
-			const codeContent = codeEl.html();
-			const matches = codeContent ? codeContent.match( /(?:<|&lt;)\/?[a-z]+?(?:&gt;|>)/g ) : null;
+		// If the code element declares a language we recognize, skip (parity with original `return true`).
+		if ( hasAnyClass( code, [ 'html', 'js', 'php', 'css', 'java' ] ) ) {
+			continue;
+		}
 
-			if ( matches && matches.length >= 2 ) {
-				codeEl.addClass( 'html' );
-			}
+		// Inspect inner HTML of <code> (serialized children) to detect HTML-like patterns.
+		const codeInner = code ? render( getChildren( code ) || [] ) : null;
+		const matches = codeInner ? codeInner.match( /(?:<|&lt;)\/?[a-z]+?(?:&gt;|>)/g ) : null;
 
-			$( this ).replaceWith( $( this ).toString().replace( /\t/g, '    ' ) );
-		} );
+		if ( matches && matches.length >= 2 && code ) {
+			addClass( code, 'html' );
+		}
+
+		// Normalize tabs to 4 spaces within the <pre> subtree (mirrors string replace in original).
+		replaceTabsInTextNodes( pre );
 	}
 
-	page.content = $.html();
+	page.content = render( doc );
+	return page;
 } );
+
+/**
+ * Adds a class to an element's "class" attribute if not already present.
+ */
+function addClass( el, className ) {
+	if ( !el ) {
+		return;
+	}
+
+	const current = hasAttrib( el, 'class' ) ? el.attribs.class : '';
+	const parts = current ? current.split( /\s+/ ).filter( Boolean ) : [];
+
+	if ( !parts.includes( className ) ) {
+		parts.push( className );
+		el.attribs.class = parts.join( ' ' );
+	}
+}
+
+/**
+ * Checks whether an element has *any* of the provided classes.
+ */
+function hasAnyClass( el, classes ) {
+	if ( !el || !hasAttrib( el, 'class' ) ) {
+		return false;
+	}
+
+	const current = el.attribs.class || '';
+	const set = new Set( current.split( /\s+/ ).filter( Boolean ) );
+
+	for ( const cls of classes ) {
+		if ( set.has( cls ) ) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Replaces tabs with four spaces in all text nodes within a subtree.
+ * Mirrors the original behavior of serializing the <pre> and doing a string replace.
+ */
+function replaceTabsInTextNodes( root ) {
+	if ( !root || !root.children ) {
+		return;
+	}
+
+	for ( const child of root.children ) {
+		if ( child.type === 'text' && typeof child.data === 'string' ) {
+			child.data = child.data.replace( /\t/g, '    ' );
+		} else if ( child.children && child.children.length ) {
+			replaceTabsInTextNodes( child );
+		}
+	}
+}

package/scripts/filter/after-post-render/gloria.js

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+
+const appendCopyHeadingButtons = require( '../../utils/gloria-after-post-render/append-copy-heading-buttons' );
+const applyDesignDocClasses = require( '../../utils/gloria-after-post-render/apply-design-doc-classes' );
+const wrapTableIntoWrappers = require( '../../utils/gloria-after-post-render/wrap-table-into-wrappers' );
+
+hexo.extend.filter.register( 'after_post_render', page => {
+	if ( page.projectTheme !== 'gloria' ) {
+		return page;
+	}
+
+	let doc = parseDocument( page.content );
+	doc = appendCopyHeadingButtons( doc );
+	doc = wrapTableIntoWrappers( doc );
+	doc = applyDesignDocClasses( doc );
+	page.content = render( doc );
+
+	return page;
+}, 45 );

package/scripts/filter/after-post-render/insert-error-codes.js

@@ -5,8 +5,12 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
 const upath = require( 'upath' );
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll } = require( 'css-select' );
+const { getAttributeValue } = require( 'domutils' );
+const applyDesignDocClasses = require( '../../utils/gloria-after-post-render/apply-design-doc-classes' );
 
 /**
  * Support @errors tag.
@@ -14,42 +18,46 @@ const upath = require( 'upath' );
  */
 hexo.extend.filter.register( 'after_post_render', page => {
 	const errorsTagMatch = /{@errors}/.exec( page.content );
-	// jscs:disable
-	const relativeUrlHelper = hexo.extend.helper.store.relative_url;
-	// jscs:enable
+	const errorsHtml = hexo.projectGlobals[ page.projectName ]?.errorsHtml;
 
-	if ( !errorsTagMatch || !hexo.projectGlobals[ page.projectName ] || !hexo.projectGlobals[ page.projectName ].errorsHtml ) {
+	if ( !errorsTagMatch || !errorsHtml ) {
 		return;
 	}
 
-	const errorsHtml = hexo.projectGlobals[ page.projectName ].errorsHtml;
-	const $ = cheerio.load( errorsHtml, null, false );
+	const relativeUrlHelper = hexo.extend.helper.store.relative_url;
+	const doc = parseDocument( errorsHtml );
 
 	// Errors are used in guides so links must be converted to have proper paths. Converting links to API here.
-	$( 'a[href]' ).each( function() {
-		const href = $( this ).attr( 'href' );
+	for ( const a of selectAll( 'a[href]', doc ) ) {
+		const href = getAttributeValue( a, 'href' );
 
-		// Ignore external links, error anchors and links with / which means they're not links to api.
-		if ( /[a-z:]*\/\//.exec( href ) || /^#.*/.exec( href ) || href.split( '/' ).length > 1 ) {
-			return;
+		// Ignore external links, error anchors and links with / which means they're not links to API.
+		if ( /[a-z:]*\/\//.test( href ) || /^#/.test( href ) || href.split( '/' ).length > 1 ) {
+			continue;
 		}
 
-		const groups = hexo.projectGlobals[ page.projectName ].groups;
-		const apiSlug = groups.find( g => g.id === 'api-reference' ).slug;
-		const hrefPath = upath.join( page.BASE_PATH, apiSlug, href );
+		const groups = hexo.projectGlobals[ page.projectName ].groups || [];
+		const apiGroup = groups.find( g => g.id === 'api-reference' );
 
-		$( this ).attr( 'href', relativeUrlHelper( page.path, hrefPath ) );
-	} );
+		if ( !apiGroup?.slug ) {
+			continue;
+		}
+
+		const hrefPath = upath.join( page.BASE_PATH, apiGroup.slug, href );
+		a.attribs.href = relativeUrlHelper( page.path, hrefPath );
+	}
 
 	// Converting links to guides created from {@glink}s.
-	$( 'a[data-glink]' ).each( function() {
-		const href = $( this ).attr( 'href' ).replace( '../', '' );
-		const hrefPath = upath.join( page.BASE_PATH, href );
+	for ( const a of selectAll( 'a[data-glink]', doc ) ) {
+		const rawHref = getAttributeValue( a, 'href' ) || '';
+		const normalized = rawHref.replace( '../', '' );
+		const hrefPath = upath.join( page.BASE_PATH, normalized );
+
+		a.attribs.href = relativeUrlHelper( page.path, hrefPath );
+	}
 
-		$( this ).attr( 'href', relativeUrlHelper( page.path, hrefPath ) );
-	} );
+	applyDesignDocClasses( doc );
 
-	page.content = page.content.replace( /<p[^>]*>{@errors}<\/p>/g, () => {
-		return $.html();
-	} );
-}, 39 );
+	// Insert processed errors HTML in place of the {@errors} paragraph.
+	page.content = page.content.replace( /<p[^>]*>{@errors}<\/p>/g, () => render( doc.children ) );
+}, 46 );

package/scripts/filter/after-post-render/validate-after-render.js

@@ -5,7 +5,8 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { selectOne } = require( 'css-select' );
 
 /**
  * Make sure each page has a title.
@@ -19,14 +20,34 @@ hexo.extend.filter.register( 'after_post_render', page => {
 		return;
 	}
 
-	const $ = cheerio.load( page.content, null, false );
-	const title = $( 'h1:not( .live-snippet h1 )' ).first();
+	const doc = parseDocument( page.content );
+	const titleEl = selectOne( 'h1:not(.live-snippet h1)', doc );
 
-	if ( !title.length && !page.title ) {
+	if ( !titleEl && !page.title ) {
 		console.error( `Document: ${ page.source } has no title and no h1 which could be used as a title.` );
 	}
 
-	if ( !page.title ) {
-		page.title = title.children().remove().end().text().trim();
+	if ( !page.title && titleEl ) {
+		page.title = getOwnText( titleEl ).trim();
 	}
 }, 32 );
+
+/**
+ * Concatenates the data of all direct text-node children of `el`.
+ * (Equivalent to removing all child elements, then taking `.text()`.)
+ */
+function getOwnText( el ) {
+	if ( !el || !el.children ) {
+		return '';
+	}
+
+	let out = '';
+
+	for ( const child of el.children ) {
+		if ( child.type === 'text' && typeof child.data === 'string' ) {
+			out += child.data;
+		}
+	}
+
+	return out;
+}

package/scripts/filter/after-render/process-svg.js

@@ -0,0 +1,21 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const inlineSvg = require( '../../utils/inline-svg' );
+const spritesheetSvg = require( '../../utils/spritesheet-svg' );
+const hexoManager = require( '../../../src/hexo-manager' );
+
+hexo.extend.filter.register( 'after_render:html', html => {
+	let doc = parseDocument( html );
+
+	doc = spritesheetSvg( doc, hexoManager.hexo.theme_dir );
+	doc = inlineSvg( doc, hexoManager.hexo.theme_dir );
+
+	return render( doc );
+}, 500 );

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

@@ -5,7 +5,11 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { cloneNode } = require( 'domhandler' );
+const { default: render } = require( 'dom-serializer' );
+const { selectAll, selectOne } = require( 'css-select' );
+const { getAttributeValue, getChildren, replaceElement } = require( 'domutils' );
 const createPrerenderPugTemplate = require( '../../../utils/pug-renderer/create-prerender-pug-template' );
 
 /**
@@ -42,16 +46,16 @@ const POST_RENDER_COMPONENTS = [
 				}
 			} );
 
-			return $element => {
-				const $code = $element.find( 'code' );
+			return element => {
+				const codeEl = selectOne( 'code', element );
 
-				if ( !$code.length ) {
+				if ( !codeEl ) {
 					return null;
 				}
 
 				// Get the language from the class (e.g., "language-js" -> "js")
-				const language = $code.attr( 'class' ).replace( 'doc', '' ).trim();
-				const code = $code.html();
+				const language = getAttributeValue( codeEl, 'class' ).replace( 'doc', '' ).trim();
+				const code = render( getChildren( codeEl ) || [] );
 
 				return template( {
 					code,
@@ -69,29 +73,36 @@ hexo.extend.filter.register( 'after_post_render', page => {
 	}
 
 	try {
-		let $ = null;
+		let doc = null;
 		let hasChanges = false;
 
-		POST_RENDER_COMPONENTS.forEach( component => {
+		for ( const component of POST_RENDER_COMPONENTS ) {
 			if ( component.fastCheck && !component.fastCheck( page.content ) ) {
-				return;
+				continue;
 			}
 
-			$ = $ || cheerio.load( page.content, null, false );
+			doc ||= parseDocument( page.content );
 
-			$( component.selector ).each( ( i, element ) => {
-				const $element = $( element );
-				const replacement = component.handler( $element, { hexo, page } );
+			for ( const el of selectAll( component.selector, doc ) ) {
+				const replacement = component.handler( el, { hexo, page } );
 
-				if ( replacement ) {
-					$element.replaceWith( replacement );
+				if ( !replacement ) {
+					continue;
+				}
+
+				// Parse the replacement HTML and swap it in (assumes a single root element from the component).
+				const replacementEl = parseFirstElement( replacement );
+
+				if ( replacementEl ) {
+					// Clone to avoid moving nodes across documents.
+					replaceElement( el, cloneNode( replacementEl, true ) );
 					hasChanges = true;
 				}
-			} );
-		} );
+			}
+		}
 
 		if ( hasChanges ) {
-			page.content = $.html();
+			page.content = render( doc );
 		}
 	} catch ( error ) {
 		console.error( error );
@@ -100,3 +111,20 @@ hexo.extend.filter.register( 'after_post_render', page => {
 
 	return page;
 }, 100 );
+
+/**
+ * Parses an HTML fragment and returns the first element node (skips text/whitespace).
+ */
+function parseFirstElement( html ) {
+	const frag = parseDocument( html );
+	// Prefer body children if present (some parsers wrap fragments).
+	const body = selectOne( 'body', frag );
+	const nodes = body ? body.children : frag.children;
+
+	for ( const n of nodes || [] ) {
+		if ( n && n.type === 'tag' ) {
+			return n;
+		}
+	}
+	return null;
+}

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

@@ -5,7 +5,9 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { selectOne } = require( 'css-select' );
+
 const CACHED_TITLES = new Map();
 
 hexo.extend.helper.register( 'uExtractAndCacheTitle', ( cacheKey, data ) => {
@@ -17,14 +19,11 @@ hexo.extend.helper.register( 'uExtractAndCacheTitle', ( cacheKey, data ) => {
 		return CACHED_TITLES.get( cacheKey );
 	}
 
-	const $ = cheerio.load( data, null, false );
-	const title = $( 'h1:not( .live-snippet h1 )' ).first();
+	const doc = parseDocument( data );
+	const titleEl = selectOne( 'h1:not(.live-snippet h1)', doc );
+
 	const formattedTitle = (
-		title
-			.children()
-			.remove()
-			.end()
-			.text()
+		getOwnText( titleEl )
 			.trim()
 			.replace( /</g, '&lt;' )
 			.replace( />/g, '&gt;' )
@@ -34,3 +33,23 @@ hexo.extend.helper.register( 'uExtractAndCacheTitle', ( cacheKey, data ) => {
 
 	return formattedTitle;
 } );
+
+/**
+ * Concatenates the data of all direct text-node children of `el`.
+ * (Equivalent to removing all child elements, then taking `.text()`.)
+ */
+function getOwnText( el ) {
+	if ( !el || !el.children ) {
+		return '';
+	}
+
+	let out = '';
+
+	for ( const child of el.children ) {
+		if ( child.type === 'text' && typeof child.data === 'string' ) {
+			out += child.data;
+		}
+	}
+
+	return out;
+}

package/scripts/helper/u-split-to-title-and-content.js

@@ -5,20 +5,44 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { parseDocument } = require( 'htmlparser2' );
+const { default: render } = require( 'dom-serializer' );
+const { selectOne } = require( 'css-select' );
+const { removeElement } = require( 'domutils' );
 
 hexo.extend.helper.register( 'uSplitToTitleAndContent', data => {
-	const $ = cheerio.load( data, null, false );
-	const title = $( 'h1:not( .live-snippet h1 )' ).first().remove();
+	const doc = parseDocument( data );
+	const titleEl = selectOne( 'h1:not(.live-snippet h1)', doc );
+
+	if ( titleEl ) {
+		removeElement( titleEl );
+	}
 
 	return {
-		title: title.children()
-			.remove()
-			.end()
-			.text()
+		title: getOwnText( titleEl )
 			.trim()
 			.replace( /</g, '&lt;' )
 			.replace( />/g, '&gt;' ),
-		content: $.html()
+		content: render( doc )
 	};
 } );
+
+/**
+ * Concatenates the data of all direct text-node children of `el`.
+ * (Equivalent to removing all child elements, then taking `.text()`.)
+ */
+function getOwnText( el ) {
+	if ( !el || !el.children ) {
+		return '';
+	}
+
+	let out = '';
+
+	for ( const child of el.children ) {
+		if ( child.type === 'text' && typeof child.data === 'string' ) {
+			out += child.data;
+		}
+	}
+
+	return out;
+}