umberto 10.7.4 → 10.8.0

package/CHANGELOG.md

@@ -1,52 +1,43 @@
 Changelog
 =========
 
-## [10.7.4](https://github.com/cksource/umberto/compare/v10.7.3...v10.7.4) (July 27, 2026)
+## [10.8.0](https://github.com/cksource/umberto/compare/v10.7.5...v10.8.0) (September 7, 2026)
 
-### Other changes
+### Features
 
-* This release does not include any user-facing changes. It was published solely to verify the release process.
+* Added support for the `llmsTxtProjects` configuration option, which lists the projects that publish an `llms.txt` index. Documentation pages in the Gloria theme now emit `<link rel="alternate" type="text/markdown">` for their own `.md` counterpart, and pages of a listed project also emit `<link rel="describedby">` for that project's index. The documentation landing page points at the `llms.txt` file of the website instead.
 
 
-## [10.7.3](https://github.com/cksource/umberto/compare/v10.7.2...v10.7.3) (July 22, 2026)
+## [10.7.5](https://github.com/cksource/umberto/compare/v10.7.4...v10.7.5) (August 13, 2026)
 
 ### Bug fixes
 
-* Fixed live snippets failing to load in browsers that require import maps before module scripts.
-
-
-## [10.7.2](https://github.com/cksource/umberto/compare/v10.7.1...v10.7.2) (July 16, 2026)
+* The hierarchy of a class or an interface rendered in the API docs built from Typedoc output now contains the full inheritance chain instead of the first level only. Derived classes, derived interfaces, and implementing classes are also resolved transitively, so the "Subclasses", "Implemented by", and "Implements" lists match the behavior of the JSDoc-based pipeline.
 
 ### Other changes
 
-* Replaced webpack with Rolldown for building theme scripts. The theme bundles are now built as ES modules with code splitting and loaded via `<script type="module">`, keeping dynamically imported dependencies (such as the shiki grammars in the Gloria theme) in separate, lazily loaded chunks. The output targets ES2022 instead of the Babel-transpiled ES5, and `webpack`, `babel-loader`, `@babel/core`, and `@babel/preset-env` are no longer dependencies of the package.
-
+* Unified the rendering of optional properties and parameters in the API documentation in the Gloria theme. Optional members are now marked with the TypeScript question mark suffix, and the separator between a member name and its type no longer contains a space before the colon, matching the TypeScript syntax (for example `options?: Object` instead of `[ options ] : Object`). Previously, optional parameters were wrapped in square brackets and optional properties had the `undefined` type appended to their type lists.
 
-## [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.
+## [10.7.4](https://github.com/cksource/umberto/compare/v10.7.3...v10.7.4) (July 27, 2026)
 
 ### 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%.
+* This release does not include any user-facing changes. It was published solely to verify the release process.
 
 
-## [10.7.0](https://github.com/cksource/umberto/compare/v10.6.1...v10.7.0) (July 2, 2026)
+## [10.7.3](https://github.com/cksource/umberto/compare/v10.7.2...v10.7.3) (July 22, 2026)
 
-### Features
+### Bug fixes
 
-* Enabled MCP install menu in the Kapa widget.
+* Fixed live snippets failing to load in browsers that require import maps before module scripts.
 
-### 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`.
+## [10.7.2](https://github.com/cksource/umberto/compare/v10.7.1...v10.7.2) (July 16, 2026)
 
 ### 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.
+* Replaced webpack with Rolldown for building theme scripts. The theme bundles are now built as ES modules with code splitting and loaded via `<script type="module">`, keeping dynamically imported dependencies (such as the shiki grammars in the Gloria theme) in separate, lazily loaded chunks. The output targets ES2022 instead of the Babel-transpiled ES5, and `webpack`, `babel-loader`, `@babel/core`, and `@babel/preset-env` are no longer dependencies of the package.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "10.7.4",
+  "version": "10.8.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "type": "module",

package/src/data-converter/converters/typedoc/typedocconverter.js

@@ -89,6 +89,9 @@ export class TypedocConverter {
 			this._convertChild( child );
 		}
 
+		// Resolve full inheritance chains while all doclets still carry their original signatures.
+		this._buildHierarchy();
+
 		// Then, when all doclets are specified, let's align types.
 		for ( const doclet of this._doclets ) {
 			// Skip source if the `file` property is not specified.
@@ -101,28 +104,6 @@ export class TypedocConverter {
 				continue;
 			}
 
-			// TODO: Could we get a deep list of all inheritance/derived?
-			// Map parent references of classes and interfaces...
-			if ( 'augmentsNested' in doclet ) {
-				const extendedTypes = doclet._signature.extendedTypes || [];
-
-				doclet.augmentsNested = extendedTypes.flatMap( getHierarchyCallback( this._typeConverter ) );
-			}
-
-			// ...but also, the derived instances...
-			if ( 'descendants' in doclet ) {
-				const extendedBy = doclet._signature.extendedBy || [];
-
-				doclet.descendants = extendedBy.flatMap( getHierarchyCallback( this._typeConverter ) );
-			}
-
-			// ...and implemented interfaces.
-			if ( 'implementsNested' in doclet ) {
-				const implementedTypes = doclet._signature.implementedTypes || [];
-
-				doclet.implementsNested = implementedTypes.flatMap( getHierarchyCallback( this._typeConverter ) );
-			}
-
 			// Unify the `_signature` tuple, so all doclets use the same algorithm.
 			if ( !Array.isArray( doclet._signature ) ) {
 				doclet._signature = [ doclet._signature, doclet._signature ];
@@ -185,6 +166,92 @@ export class TypedocConverter {
 			} );
 	}
 
+	/**
+	 * Fills the `augmentsNested`, `implementsNested`, and `descendants` properties of class and interface doclets
+	 * with full inheritance chains. Typedoc signatures (`extendedTypes`, `implementedTypes`, `extendedBy`) describe
+	 * only the first level of the hierarchy, so ancestor references are followed transitively through the converted
+	 * doclets.
+	 *
+	 * The `augmentsNested` chain continues only through ancestors of the same kind. Ancestors of an interface mixed
+	 * into a class hierarchy (an intersection in `extendedTypes`) extend the list of implemented interfaces instead
+	 * of the inheritance chain rendered on a page. Descendants are calculated by inverting the resolved ancestor
+	 * relations, so both directions of the hierarchy stay consistent.
+	 *
+	 * @protected
+	 */
+	_buildHierarchy() {
+		const docletsByLongname = new Map( this._doclets.map( doclet => [ doclet.longname, doclet ] ) );
+		const hierarchyDoclets = this._doclets.filter( doclet => doclet._signature && 'augmentsNested' in doclet );
+		const relationsCache = new Map();
+
+		const resolveRelations = doclet => {
+			if ( relationsCache.has( doclet ) ) {
+				return relationsCache.get( doclet );
+			}
+
+			const relations = { augmentsNested: [], implementsNested: [] };
+
+			// Fill the cache upfront to break potential reference cycles.
+			relationsCache.set( doclet, relations );
+
+			const collect = ( references, relationName ) => {
+				for ( const reference of references.flatMap( flattenHierarchyReference ) ) {
+					const longname = this._typeConverter.convertReference( reference );
+
+					relations[ relationName ].push( longname );
+
+					const ancestor = docletsByLongname.get( longname );
+
+					if ( !ancestor || !ancestor._signature || !( 'augmentsNested' in ancestor ) ) {
+						continue;
+					}
+
+					const ancestorRelations = resolveRelations( ancestor );
+
+					if ( relationName === 'augmentsNested' && ancestor.kind === doclet.kind ) {
+						relations.augmentsNested.push( ...ancestorRelations.augmentsNested );
+						relations.implementsNested.push( ...ancestorRelations.implementsNested );
+					} else {
+						relations.implementsNested.push( ...ancestorRelations.augmentsNested, ...ancestorRelations.implementsNested );
+					}
+				}
+			};
+
+			collect( doclet._signature.extendedTypes || [], 'augmentsNested' );
+			collect( doclet._signature.implementedTypes || [], 'implementsNested' );
+
+			relations.augmentsNested = [ ...new Set( relations.augmentsNested ) ].filter( name => name !== doclet.longname );
+			relations.implementsNested = [ ...new Set( relations.implementsNested ) ].filter( name => name !== doclet.longname );
+
+			return relations;
+		};
+
+		for ( const doclet of hierarchyDoclets ) {
+			const relations = resolveRelations( doclet );
+
+			doclet.augmentsNested = relations.augmentsNested;
+
+			if ( 'implementsNested' in doclet ) {
+				doclet.implementsNested = relations.implementsNested;
+			}
+
+			doclet.descendants = [];
+		}
+
+		for ( const doclet of hierarchyDoclets ) {
+			const relations = resolveRelations( doclet );
+			const ancestors = new Set( [ ...relations.augmentsNested, ...relations.implementsNested ] );
+
+			for ( const longname of ancestors ) {
+				const ancestor = docletsByLongname.get( longname );
+
+				if ( ancestor && 'descendants' in ancestor && ancestor.descendants ) {
+					ancestor.descendants.push( doclet.longname );
+				}
+			}
+		}
+	}
+
 	/**
 	 * @protected
 	 * @param {BaseReflection} reflection
@@ -964,17 +1031,18 @@ class TypeConverter {
 }
 
 /**
- * @param {TypeConverter} converter
- * @returns {Function}
+ * Flattens an intersection found in a hierarchy relation (for example, `class Foo extends Mixin( Base )` produces
+ * `Base & SomeInterface` in `extendedTypes`) into a list of plain references.
+ *
+ * @param {AvailableTypes} reference
+ * @returns {Array.<ReferenceType>}
  */
-function getHierarchyCallback( converter ) {
-	return reference => {
-		if ( reference.type === 'intersection' ) {
-			return reference.types.map( ref => converter.convertReference( ref ) );
-		}
+function flattenHierarchyReference( reference ) {
+	if ( reference.type === 'intersection' ) {
+		return reference.types;
+	}
 
-		return converter.convertReference( reference );
-	};
+	return [ reference ];
 }
 
 function mapIndexSignatureObject( subItem, index ) {

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

@@ -107,6 +107,7 @@ export const projectLocals = ( ctx, {
 	disableSearch,
 	shouldInjectNoIndexMeta,
 	og,
+	llmsTxtProjects,
 	quickNavigationProjects,
 	navigationShowEmptyCategories
 } = {} ) => {
@@ -197,5 +198,6 @@ export const projectLocals = ( ctx, {
 		locals.isLts = /\/ckeditor5\/(lts-v\d+)(?:\/|$)/.test( `/${ locals.path }` );
 
 		locals.mainOg = og || {};
+		locals.llmsTxtProjects = llmsTxtProjects || [];
 	} );
 };

package/src/tasks/build-documentation.js

@@ -156,6 +156,7 @@ export const buildDocumentation = options => {
 				extraStyles,
 				extraScripts,
 				og: mainConfig.og,
+				llmsTxtProjects: mainConfig.llmsTxtProjects || [],
 				additionalDocumentation: mainConfig.additionalDocumentation,
 				canonicalUrlBeginning: mainConfig.canonicalUrlBeginning,
 				macrosVariables: mainConfig.variables,
@@ -321,6 +322,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,
 				og: options.og,
+				llmsTxtProjects: options.llmsTxtProjects,
 				canonicalUrlBeginning: options.canonicalUrlBeginning,
 				macrosVariables: options.macrosVariables,
 				quickNavigationProjects: options.quickNavigationProjects
@@ -343,6 +345,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			vwo: options.vwo,
 			feedbackWidget: options.feedbackWidget,
 			og: options.og,
+			llmsTxtProjects: options.llmsTxtProjects,
 			canonicalUrlBeginning: options.canonicalUrlBeginning,
 			macrosVariables: options.macrosVariables,
 			quickNavigationProjects: options.quickNavigationProjects
@@ -405,6 +408,7 @@ async function buildProjects( rootPath, projectPaths, options = {} ) {
 			extraScriptsPaths: extraScripts,
 			disableSearch: options.disableSearch,
 			og: options.og,
+			llmsTxtProjects: options.llmsTxtProjects,
 			// Force displaying empty categories in the navigation tree when the documentation is being built partially.
 			navigationShowEmptyCategories: Array.isArray( guidesToProcess )
 		} );
@@ -515,6 +519,7 @@ async function buildApis( projectConfigs, options = {} ) {
 				feedbackWidget: options.feedbackWidget,
 				pathJoin: upath.join,
 				mainOg: options.og || {},
+				llmsTxtProjects: options.llmsTxtProjects || [],
 				isNightly: options.docSearch?.indexName?.includes( 'nightly' ) || false,
 				isLts: /\/ckeditor5\/(lts-v\d+)(?:\/|$)/.test( `/${ BASE_PATH }` )
 			},
@@ -596,7 +601,9 @@ function buildSdks( projectConfigs, options = {} ) {
 				vwo: options.vwo,
 				feedbackWidget: options.feedbackWidget,
 				pathJoin: upath.join,
-				mainOg: options.og || {}
+				mainOg: options.og || {},
+				llmsTxtProjects: options.llmsTxtProjects || [],
+				isLts: /\/ckeditor5\/(lts-v\d+)(?:\/|$)/.test( `/${ BASE_PATH }` )
 			},
 			projectConfig: config,
 			canonicalUrlBeginning: getCanonicalBeginning( { config, options, hexoManager } )

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

@@ -26,17 +26,19 @@ mixin method( met )
 					code.api-item-heading__code
 						a.doc.b-link( class="member-name" href="#" + id ) #{ met.name }
 
-						//- params ( param1, [param2] )
+						//- params ( param1, param2? )
 						| (
 						if isNonEmptyArray( met.params )
 							each param, index in met.params
 								if param.optional
-									|  [ #{ param.name } ]
+									|  #{ param.name }?
 								else
 									|  #{ param.name }
 								if ( param.subParamsString )
 									//- Allow rendering HTML from the `subParamsString` as it may contain links to other pages.
-									| !{ param.subParamsString }
+									//- The string is prebuilt by the shared `api-builder` with the legacy `[name]`
+									//- convention for optional members, so convert it to the `name?` syntax here.
+									| !{ param.subParamsString.replace( /\[([\w$.]+)\]/g, '$1?' ) }
 								if index < met.params.length - 1
 									|,
 								else

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

@@ -14,21 +14,28 @@ mixin paramsMixin ( params, level, title )
 
             dt
                 code
+                    //- Consecutive piped text lines are joined with a newline, which renders as
+                    //- a space. To keep the TypeScript-style `name?: Type` notation, the colon
+                    //- must live in the same text node as the name.
+                    - const hasTypes = isNonEmptyArray( param.types );
+
                     if isComputedProperty
                         - const [ parentParam, nestedParam ] = param.name.split( '.' );
 
                         | #{ parentParam }
                         i
                             | #{ nestedParam }
-                    else if param.optional
-                        | [ #{ param.name } ]
+                        if hasTypes
+                            | :!{ ' ' }
+                            +type( param.types )
                     else
-                        | #{ param.name }
+                        - const displayName = param.optional ? `${ param.name }?` : param.name;
 
-                    if isNonEmptyArray( param.types )
-                        | :
-                        | !{ ' ' }
-                        +type( param.types )
+                        if hasTypes
+                            | #{ displayName }:!{ ' ' }
+                            +type( param.types )
+                        else
+                            | #{ displayName }
 
             dd
                 if ( param.description )

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

@@ -19,11 +19,11 @@ mixin property( prop )
 			h3
 				div.api-item-heading
 					code.api-item-heading__code
-						a.doc.b-link( class="member-name" href="#" + prop.id ) #{ prop.name }
+						a.doc.b-link( class="member-name" href="#" + prop.id ) #{ prop.optional ? prop.name + '?' : prop.name }
 
 						if isNonEmptyArray( prop.types )
-							|  :!{' '}
-							+type( prop.types, prop.optional )
+							| :!{' '}
+							+type( prop.types )
 					if isNonEmptyArray( prop.badges )
 						+tagWrapper()
 							each badge in prop.badges

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

@@ -1,16 +1,12 @@
 include ./_link-or-text.pug
 
-mixin type( types, isOptional = false )
+mixin type( types )
 	each nameOrObject, index in types
 		+renderType( nameOrObject )
 
 		if index < types.length - 1
 			| !{ ' | ' }
 
-	if ( isOptional && !types.includes( 'undefined' ) )
-		| !{ ' | ' }
-		+renderType( 'undefined' )
-
 //- TODO: Description.
 //-
 //- @param {String|*} inlineObjectOrType

package/themes/umberto/layout/gloria/_api-docs/_mixin/type-parameter.pug

@@ -8,7 +8,7 @@ mixin typeParameter( type )
 			//- We mark most TypeScript types as `object`, as their structure is complex.
 			//- Hence, it does not really make sense to show that a type extends an unknown `object`.
 			if ( type.value && type.value[ 0 ] !== 'object' )
-				| !{' : '}
+				| !{': '}
 				if ( type.isExtending )
 					i !{ 'extends ' }
 				+type( type.value )

package/themes/umberto/layout/gloria/_api-docs/_partial/type-parameters.pug

@@ -18,7 +18,7 @@ if isNonEmptyArray( data.typeParameters )
 								//- We mark most TypeScript types as `object`, as their structure is complex.
 								//- Hence, it does not really make sense to show that a type extends an unknown `object`.
 								if ( type.value && type.value[ 0 ] !== 'object' )
-									| !{' : '}
+									| !{': '}
 									if ( type.isExtending )
 										i !{ 'extends ' }
 									+type( type.value )

package/themes/umberto/layout/gloria/_head/head.pug

@@ -49,6 +49,26 @@ if ( page[ 'dc-description' ] || ogConfig.description )
 if page.BASE_PATH && page.BASE_PATH !== '.' && !page.BASE_PATH.includes( 'latest' )
 	link( rel = 'canonical' href = page.canonicalUrlBeginning + page.path.replace( page.BASE_PATH, projectLocals.latestBasePath ) )
 
+//- The `docs` build writes a Markdown counterpart for `*/latest/**` pages only. That rules out the LTS output,
+//- and it is why these relations cannot sit inside the `canonical` guard above, which skips `latest` projects.
+- const projects = llmsTxtProjects || [];
+- const buildGeneratesMarkdown = projects.length > 0 && !isLts;
+- const markdownProjectKey = page.BASE_PATH && page.BASE_PATH !== '.' ? page.BASE_PATH.split( '/' )[ 0 ] : null;
+- const hasMarkdownVersion = markdownProjectKey && buildGeneratesMarkdown && !page.path.includes( '/getting-started/legacy/' );
+
+if hasMarkdownVersion
+	link( rel = 'alternate' type = 'text/markdown' href = relative_url( page.path, page.path.replace( /\.html$/, '.md' ) ) )
+
+	if projects.includes( markdownProjectKey )
+		if page.groupId === 'api-reference'
+			link( rel = 'describedby' href = 'llms.txt' )
+		else
+			link( rel = 'describedby' href = relative_url( page.path, markdownProjectKey + '/llms.txt' ) )
+
+//- The way in for an agent that arrives from the website rather than from an article.
+else if !markdownProjectKey && mainOg && mainOg.hostname
+	link( rel = 'describedby' href = mainOg.hostname + '/llms.txt' )
+
 if page.isSnippetPage
 	//UMBERTO: SNIPPET: HEAD