umberto 10.6.1 → 10.7.1

package/CHANGELOG.md

@@ -1,6 +1,33 @@
 Changelog
 =========
 
+## [10.7.1](https://github.com/cksource/umberto/compare/v10.7.0...v10.7.1) (July 15, 2026)
+
+### Bug fixes
+
+* Fixed source links for CKEditor 5 packages in API documentation so they now point to the public repository. Links for the latest documentation point to the `master` branch, and links for LTS documentation point to the matching `release-v*` branch.
+
+### Other changes
+
+* Improved the performance of the documentation build. Pug templates of XML components used in Markdown are now compiled once and reused across pages, instead of being recompiled for every component occurrence. This shortens the page generation phase by about 20%.
+
+
+## [10.7.0](https://github.com/cksource/umberto/compare/v10.6.1...v10.7.0) (July 2, 2026)
+
+### Features
+
+* Enabled MCP install menu in the Kapa widget.
+
+### Bug fixes
+
+* Fixed scrolling to a section in the Gloria theme when navigating to an anchor without a full page reload — for example, changing the anchor in the address bar, using the browser's back/forward buttons, or opening a link to a section on the current page. The target heading is now offset below the sticky header instead of being hidden beneath it.
+* Moved `chokidar` from `devDependencies` to `dependencies`. It is imported at runtime by the file watcher (`src/tasks/watcher.js`), which ships with the package, so it must be installed for consumers. Previously it resolved only by chance through a hoisted copy in the consumer's tree, which fails when the consumer enables pnpm's `enableGlobalVirtualStore` and the package is linked from the global store, outside the consumer's `node_modules`.
+
+### Other changes
+
+* The tabbed content component now sets a `data-tab-label` attribute on each tab panel, carrying the label of its tab. This exposes the label to tools that process the rendered HTML, where it otherwise lives only inside the tab button.
+
+
 ## [10.6.1](https://github.com/cksource/umberto/compare/v10.6.0...v10.6.1) (June 18, 2026)
 
 ### Other changes
@@ -30,20 +57,6 @@ Changelog
 
 * Changed the call for feedback title from `<h3>` to `<div>` to prevent it from appearing in the table of contents.
 
-
-## [10.5.0](https://github.com/cksource/umberto/compare/v10.4.1...v10.5.0) (April 14, 2026)
-
-### Features
-
-* Added the Call for feedback component for documentation pages.
-
-
-## [10.4.1](https://github.com/cksource/umberto/compare/v10.4.0...v10.4.1) (April 13, 2026)
-
-### Bug fixes
-
-* Fixed URL in the dropdown for LTS item to have absolute URL to pass documentation validation.
-
 ---
 
 To see all releases, visit the [release page](https://github.com/cksource/umberto/releases).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "10.6.1",
+  "version": "10.7.1",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "type": "module",
@@ -15,11 +15,12 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@babel/core": "^7.18.10",
-    "@babel/preset-env": "^7.29.5",
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
     "@minify-html/node": "^0.17.1",
     "@vscode/markdown-it-katex": "^1.1.2",
     "babel-loader": "^10.0.0",
+    "chokidar": "^4.0.3",
     "css-select": "^6.0.0",
     "dom-serializer": "^2.0.0",
     "domhandler": "^5.0.3",
@@ -40,7 +41,7 @@
     "jquery": "~3.7.1",
     "js-beautify": "^1.14.4",
     "lodash": "^4.17.21",
-    "markdown-it": "^14.1.1",
+    "markdown-it": "^14.2.0",
     "markdown-it-abbr": "^1.0.4",
     "markdown-it-deflist": "^2.1.0",
     "markdown-it-emoji": "^2.0.2",

package/scripts/utils/pug-to-xml-binding/render-xml-pug-components-in-markdown.cjs

@@ -9,6 +9,39 @@ const transformXMLTreeToPug = require( './transform-xml-tree-to-pug.cjs' );
 const XMLComponentsParser = require( './parser/xml-components-parser.cjs' );
 const { walkXMLTree, TreeWalkActions } = require( './parser/walk-xml-tree.cjs' );
 
+// Compiled Pug templates of component mixin calls, keyed by the generated template text.
+// Compiling a template is expensive because Pug lexes and parses the whole `include` tree
+// on every compilation, and the same mixin calls repeat across pages. The compiled function
+// is not bound to any locals, so it can be safely reused with per-page locals.
+//
+// The cache lives for the whole process, like the cache in `createPrerenderPugTemplate()`,
+// so changes to component Pug files require a restart in the watch mode.
+const compiledTemplateCache = new Map();
+
+/**
+ * Compiles a Pug template through the Hexo Pug renderer, reusing previously compiled templates.
+ *
+ * Falls back to `null` when the renderer does not support compilation, in which case the caller
+ * should render through `hexo.render.renderSync()`.
+ */
+function getCompiledPugTemplate( hexo, text, path ) {
+	const cacheKey = `${ path }\n${ text }`;
+	let template = compiledTemplateCache.get( cacheKey );
+
+	if ( !template ) {
+		const pugRenderer = hexo.render.renderer?.get( 'pug' );
+
+		if ( !pugRenderer?.compile ) {
+			return null;
+		}
+
+		template = pugRenderer.compile( { text, path } );
+		compiledTemplateCache.set( cacheKey, template );
+	}
+
+	return template;
+}
+
 /**
  * Slices XML components from Markdown content and transforms them to Pug format.
  *
@@ -93,14 +126,18 @@ function renderXMLPugComponentsInMarkdown( xml, options ) {
 					let finalReplacement = null;
 
 					try {
-						finalReplacement = hexo.render.renderSync(
-							{
-								engine: 'pug',
-								text: content,
-								path: basePath
-							},
-							locals
-						).trim();
+						const template = getCompiledPugTemplate( hexo, content, basePath );
+
+						finalReplacement = template ?
+							template( locals ).trim() :
+							hexo.render.renderSync(
+								{
+									engine: 'pug',
+									text: content,
+									path: basePath
+								},
+								locals
+							).trim();
 					} catch ( error ) {
 						console.error( error );
 						console.error( `Error rendering component "${ node.name }" in file ${ sourceName }` );

package/src/api-builder/api-builder.js

@@ -19,6 +19,7 @@ import { getShortModulePath } from '../helpers/get-short-module-path.js';
 import { getDocsearchConfig as getDocSearchConfig } from '../helpers/get-docsearch-config.js';
 import { splitLongname } from '../helpers/split-longname.js';
 import { getIssueUrl, getFullGithubLink } from '../helpers/github-url.js';
+import { rewritePublicSourceUrl } from '../helpers/rewrite-public-source-url.js';
 import getReportIssueWidgetUrl from '../../scripts/utils/getreportissuewidgeturl.cjs';
 import { randomId } from '../../scripts/utils/random-id.cjs';
 import parseHref from '../../scripts/utils/parse-href.cjs';
@@ -521,6 +522,7 @@ export class ApiBuilder {
 					groups,
 					seeSourceRepositoryUrl: this._projectConfig.github !== undefined ? this._projectConfig.github.url : realImportPath,
 					getLinkToSource: getFullGithubLink.bind( this ),
+					rewritePublicSourceUrl: url => rewritePublicSourceUrl( url, this._projectConfig.ckeditor5SourceLinkBranch ),
 					docSearchConfig: getDocSearchConfig( this._docSearch, {
 						groups: this._groups,
 						slug: this._projectSlug,

package/src/helpers/rewrite-public-source-url.js

@@ -0,0 +1,42 @@
+/**
+ * @license Copyright (c) 2017-2026, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * Rewrites CKEditor 5 public package source links generated from the commercial repository checkout.
+ *
+ * @param {String} sourceUrl
+ * @param {String} sourceBranch
+ * @returns {String}
+ */
+export function rewritePublicSourceUrl( sourceUrl, sourceBranch ) {
+	if ( !sourceUrl || !sourceBranch ) {
+		return sourceUrl;
+	}
+
+	let url;
+
+	try {
+		url = new URL( sourceUrl );
+	} catch {
+		return sourceUrl;
+	}
+
+	if ( url.hostname !== 'github.com' ) {
+		return sourceUrl;
+	}
+
+	const match = url.pathname.match( /^\/[^/]+\/ckeditor5-commercial\/blob\/[^/]+\/external\/ckeditor5\/(.+)$/ );
+
+	if ( !match ) {
+		return sourceUrl;
+	}
+
+	return [
+		'https://github.com/ckeditor/ckeditor5',
+		'blob',
+		sourceBranch,
+		match[ 1 ]
+	].join( '/' ) + url.search + url.hash;
+}

package/src/tasks/get-project-config.js

@@ -92,6 +92,7 @@ export const getProjectConfig = async ( rootPath, options = {} ) => {
 	validateConfiguration( config );
 
 	config.version = getProjectVersion( rootPath );
+	config.ckeditor5SourceLinkBranch = getCKEditor5SourceLinkBranch( rootPath, config );
 
 	parseGitHubUrls( config, rootPath );
 
@@ -304,6 +305,44 @@ function getProjectVersion( rootPath ) {
 	return version || 'latest';
 }
 
+/**
+ * Returns CKEditor 5 source link branch based on LTS metadata from `package.json`.
+ *
+ * @param {String} rootPath
+ * @param {Object} config
+ * @param {String} config.slug
+ * @param {String} config.version
+ * @return {String|undefined}
+ */
+function getCKEditor5SourceLinkBranch( rootPath, config ) {
+	if ( config.slug !== 'ckeditor5' ) {
+		return;
+	}
+
+	const packageJson = getPackageJson( rootPath );
+	const ltsVersions = packageJson ? packageJson[ 'ck-lts-versions' ] : null;
+	const releaseLine = getReleaseLine( config.version );
+	const ltsReleaseLines = Array.isArray( ltsVersions ) ? ltsVersions.map( Number ) : null;
+
+	if ( !ltsReleaseLines || releaseLine === null ) {
+		return;
+	}
+
+	const isLtsVersion = ltsReleaseLines.includes( releaseLine );
+
+	return isLtsVersion ? `release-v${ releaseLine }` : 'master';
+}
+
+/**
+ * @param {String} version
+ * @return {Number|null}
+ */
+function getReleaseLine( version ) {
+	const match = version.match( /^(\d+)\./ );
+
+	return match ? Number( match[ 1 ] ) : null;
+}
+
 /**
  * Tries to find a URL to the repository based on the value in `package.json`, under the "repository" object.
  *

package/themes/umberto/layout/gloria/_api-docs/_mixin/_api-see-source.pug

@@ -1,7 +1,8 @@
 mixin seeSource( item )
 	//- Do not render "See source" button if the module or the parsed item (e.g. a function) has the `@skipsource` annotation
 	if ( projectLocals.seeSourceRepositoryUrl && item.file && !( data.skipSource || item.skipSource ) )
-		- const link = item.file.url || projectLocals.getLinkToSource( projectLocals.seeSourceRepositoryUrl, item.file );
+		- const sourceLink = item.file.url || projectLocals.getLinkToSource( projectLocals.seeSourceRepositoryUrl, item.file );
+		- const link = projectLocals.rewritePublicSourceUrl( sourceLink );
 
 		if link
 			.see-source

package/themes/umberto/layout/gloria/_components/tabs/index.pug

@@ -70,6 +70,7 @@ mixin tabs({ id: tabsId, ariaLabel = 'Tabbed content', className, align = 'left'
 				aria-labelledby=`${idPrefix}-${ id }-tab`
 				aria-hidden=tab.active ? 'false' : 'true'
 				data-tab-id=id
+				data-tab-label=tab.label
 				class={
 					[className]: !!className,
 					'is-spaced': tab.spaced,

package/themes/umberto/layout/gloria/_modules/kapa/index.pug

@@ -139,11 +139,32 @@ mixin load-kapa-script( kapa )
 			return projectConfig.sourceGroupIds.join( ',' );
 		}
 
+		function getMcpServerUrl() {
+			const defaultMcpServerUrl = kapa.default.mcpServerUrl || null;
+
+			if ( !projectConfig ) {
+				return defaultMcpServerUrl;
+			}
+
+			if ( !projectConfig.mcpServerUrl ) {
+				return defaultMcpServerUrl;
+			}
+
+			return projectConfig.mcpServerUrl;
+		}
+
 		attributes[ 'data-modal-title' ] = getModalTitle( projectConfig );
 		attributes[ 'data-modal-ask-ai-input-placeholder' ] = getQuestionPlaceholder();
 		attributes[ 'data-modal-example-questions' ] = getExampleQuestions();
 		attributes[ 'data-source-group-ids-include' ] = getSourceGroupIds();
 
+		const mcpServerUrl = getMcpServerUrl();
+
+		if ( mcpServerUrl ) {
+			attributes[ 'data-mcp-enabled' ] = 'true';
+			attributes[ 'data-mcp-server-url' ] = mcpServerUrl;
+		}
+
 	script&attributes(attributes)
 
 	style#custom_kapa_styles

package/themes/umberto/src/gloria/css/layout/_base.scss

@@ -5,6 +5,10 @@
 		height: 100%;
 		overscroll-behavior-y: none; /* Prevent vertical bounce, allow horizontal trackpad gestures. */
 		overflow-x: hidden;
+
+		/* Offset native fragment navigation (anchor jumps, pasting a hash URL) below the
+		   sticky header. `--header-height` is kept up to date by the header module. */
+		scroll-padding-top: calc(var(--header-height, 0px) + 32px);
 	}
 
 	body {

package/themes/umberto/src/gloria/js/components/hash-link.js

@@ -18,6 +18,10 @@ export class HashLink extends BaseComponent {
 		// Handle initial hash link navigation if present in the URL
 		this._handleInitialHash();
 
+		// Handle hash changes on an already-loaded page (e.g. editing the hash in the
+		// address bar or browser back/forward navigation).
+		this._handleHashChange();
+
 		// Add click event listener to handle hash link clicks
 		document.addEventListener( 'click', event => {
 			const target = event.target.closest( 'a[href^="#"]' );
@@ -57,4 +61,30 @@ export class HashLink extends BaseComponent {
 			} );
 		}, { once: true } );
 	}
+
+	/**
+	 * Handles hash changes that happen without a full page reload, e.g. editing the
+	 * hash in the address bar or navigating with the browser's back/forward buttons.
+	 *
+	 * In these cases the browser performs native fragment navigation, which scrolls
+	 * the target to the very top of the viewport without accounting for the sticky
+	 * header. Re-running the scroll with the proper offset keeps the heading visible.
+	 *
+	 * Clicking an `a[href^="#"]` link does not trigger this handler, because the click
+	 * handler updates the URL via `history.pushState()`, which does not emit a
+	 * `hashchange` event.
+	 *
+	 * @private
+	 */
+	static _handleHashChange() {
+		window.addEventListener( 'hashchange', () => {
+			if ( !window.location.hash ) {
+				return;
+			}
+
+			scrollToHash( window.location.hash.substring( 1 ), {
+				pushState: false
+			} );
+		} );
+	}
 }

package/themes/umberto/src/gloria/js/modules/header.js

@@ -83,6 +83,11 @@ export class Header extends BaseComponent {
 			this.element.classList.toggle( 'is-on-top-overlay', state.isOnOverlay );
 			this.dispatchHeaderResizeEvent();
 		} else if ( prevState?.height !== state.height && state.height !== null ) {
+			// Expose the header height on the document root so that native fragment navigation
+			// (e.g. pasting a URL with a hash, which fires no `hashchange` or `load` event) can
+			// offset the target below the sticky header via `scroll-padding-top`. See `_base.scss`.
+			document.documentElement.style.setProperty( '--header-height', `${ state.height }px` );
+
 			this.dispatchHeaderResizeEvent();
 		}
 	}
@@ -128,7 +133,7 @@ export class Header extends BaseComponent {
 	}
 
 	/**
-	 * Sets the header height variable on the body element.
+	 * Tracks the header height and updates the component state.
 	 */
 	_trackHeight() {
 		this.setState( {