umberto 6.1.1 → 7.0.0

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 Changelog
 =========
 
+## [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))
+
+
 ## [6.1.1](https://github.com/cksource/umberto/compare/v6.1.0...v6.1.1) (2025-04-17)
 
 ### Bug fixes

package/package.json

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

package/scripts/filter/before-post-render/has-own-favicons.js

@@ -0,0 +1,12 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const hasOwnFavicons = require( '../../utils/has-own-favicons' );
+
+hexo.extend.filter.register( 'before_post_render', data => {
+	return hasOwnFavicons( data, hexo );
+} );

package/scripts/utils/has-own-favicons.js

@@ -0,0 +1,48 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const upath = require( 'upath' );
+const fs = require( 'fs' );
+
+/**
+ * Checks if the project has its own favicons. If so, they will be used when rendering meta tags (`<link rel="icon">`).
+ *
+ * Otherwise, the default favicons will be used.
+ *
+ * @param {object} page
+ * @param {string} page.projectName
+ * @param {boolean} page.hasOwnAssets
+ * @param {object} hexo
+ * @param {Object.<string, ProjectGlobalConfig>} hexo.projectGlobals
+ * @returns {*}
+ */
+module.exports = function hasOwnFavicons( page, hexo ) {
+	const projectConfig = hexo.projectGlobals[ page.projectName ];
+
+	let hasOwnAssets = false;
+
+	if ( projectConfig ) {
+		const { config } = hexo.projectGlobals[ page.projectName ];
+
+		if ( config ) {
+			hasOwnAssets = fs.existsSync(
+				upath.join( config.projectRootPath, 'docs', 'assets', 'img', 'favicons', '96x96.png' )
+			);
+		}
+	}
+
+	page.hasOwnAssets = hasOwnAssets;
+
+	return page;
+};
+
+/**
+ * @typedef {object} ProjectGlobalConfig
+ * @property {string} projectRootPath
+ * @property {object} config
+ * @property {string} config.projectRootPath
+ */

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

@@ -79,9 +79,9 @@ module.exports = function findTargetDoclet( docletCollection, options ) {
 			return null;
 		}
 
-		const { properties = [] } = typedefItem;
+		const { properties } = typedefItem;
 
-		return properties.find( item => item.name === member ) ? typedefItem : null;
+		return ( properties || [] ).find( item => item.name === member ) ? typedefItem : null;
 	}
 
 	let targetDoclet;

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

@@ -6,6 +6,7 @@
 'use strict';
 
 const TypedocConverter = require( './typedocconverter' );
+const ReflectionKind = require( './reflectionkind' );
 
 /**
  * An abstract parser class providing basic utils for converting Typedoc reflection to JSDoc doclet.
@@ -14,14 +15,14 @@ module.exports = class AbstractParser {
 	/**
 	 * @abstract
 	 * @method canParse
-	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 
 	/**
 	 * @abstract
 	 * @method parse
-	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {BaseReflection} item
 	 * @param {String|null} [parentName=null]
 	 * @returns {Object}
 	 */
@@ -29,7 +30,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Coverts the item's comment from Markdown to HTML.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	getComment( item ) {
@@ -41,33 +42,35 @@ module.exports = class AbstractParser {
 	}
 
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @param {String|null} [parentName=null]
 	 * @returns {String}
 	 */
 	getLongName( item, parentName = null ) {
 		let separator;
 
-		switch ( item.kindString ) {
-			case 'Module':
+		if ( item.isCKEditor5Event ) {
+			separator = '#event:';
+		}
+
+		switch ( item.kind ) {
+			case ReflectionKind.Module:
 				separator = ':';
 				parentName = 'module';
 				break;
 
-			case 'Class':
-			case 'Function':
-			case 'Interface':
-			case 'Type alias':
+			case ReflectionKind.Variable:
+			case ReflectionKind.Function:
+			case ReflectionKind.Class:
+			case ReflectionKind.Interface:
+			case ReflectionKind.TypeAlias:
 				separator = '~';
 				break;
 
-			case 'Event':
-				separator = '#event:';
-				break;
-
 			default:
-				separator = this.getScope( item ) === 'static' ? '.' : '#';
-				break;
+				if ( !separator ) {
+					separator = this.getScope( item ) === 'static' ? '.' : '#';
+				}
 		}
 
 		return `${ parentName }${ separator }${ item.name }`;
@@ -76,7 +79,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Prepares the name for the computed property.
 	 *
-	 * @param {TypedocReflection<'Index signature'>} item
+	 * @param {ComputedPropertyReflection} item
 	 * @returns {String}
 	 */
 	getComputedName( item ) {
@@ -86,7 +89,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the access type for the item.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {'public'|'internal'|'protected'|'private'}
 	 */
 	getVisibility( item ) {
@@ -110,48 +113,49 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the item's kind.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	getKind( item ) {
-		switch ( item.kindString ) {
-			case 'Module':
+		if ( item.isCKEditor5Event ) {
+			return 'event';
+		}
+		if ( item.isCKEditor5Error ) {
+			return 'error';
+		}
+
+		switch ( item.kind ) {
+			case ReflectionKind.Module:
 				return 'module';
 
-			case 'Class':
+			case ReflectionKind.Class:
 				return 'class';
 
-			case 'Function':
-			case 'Method':
-			case 'Constructor':
+			case ReflectionKind.Function:
+			case ReflectionKind.Method:
+			case ReflectionKind.Constructor:
 				return 'function';
 
-			case 'Interface':
+			case ReflectionKind.Interface:
 				return 'interface';
 
-			case 'Accessor':
-			case 'Property':
-			case 'Index signature':
+			case ReflectionKind.Accessor:
+			case ReflectionKind.Property:
+			case ReflectionKind.IndexSignature:
 				return 'member';
 
-			case 'Variable':
+			case ReflectionKind.Variable:
 				return 'constant';
 
-			case 'Type alias':
+			case ReflectionKind.TypeAlias:
 				return 'typedef';
-
-			case 'Event':
-				return 'event';
-
-			case 'Error':
-				return 'error';
 		}
 	}
 
 	/**
 	 * Returns the item's scope.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {'instance'|'static'}
 	 */
 	getScope( item ) {
@@ -167,7 +171,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the `extraId` combined from the item's scope, kind, name and optional variation.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	getExtraId( item ) {
@@ -179,7 +183,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns the long names of the events that are fired from the signature.
 	 *
-	 * @param {TypedocReflectionMeta} signature
+	 * @param {BaseReflection} signature
 	 * @param {String} parentName
 	 * @returns {Array.<String>|null}
 	 */
@@ -202,7 +206,7 @@ module.exports = class AbstractParser {
 	}
 
 	/**
-	 * @param {TypedocReflectionMeta} signature
+	 * @param {BaseReflection} signature
 	 * @param {String} parentName
 	 * @returns {Array.<Object>|null}
 	 */
@@ -243,7 +247,7 @@ module.exports = class AbstractParser {
 	 * Returns the URL to GitHub with selected line, where the given doclet is defined.
 	 * The URL includes a commit hash which was used to build the API docs.
 	 *
-	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {BaseReflection} item
 	 * @param {Number} sourceIndex
 	 * @returns {Object|null}
 	 */
@@ -264,7 +268,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Returns links from the "@see" tags.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @param {String|null} [parentName=null]
 	 * @returns {Array.<String>}
 	 */
@@ -308,7 +312,7 @@ module.exports = class AbstractParser {
 	 *
 	 * The readonly state can be marked either by a TypeScript `readonly` keyword, or by the `@readonly` JSDoc keyword.
 	 *
-	 * @param {TypedocReflection} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isReadonly( item ) {
@@ -324,7 +328,7 @@ module.exports = class AbstractParser {
 	 *
 	 * The observable state can be marked by the `@observable` JSDoc keyword.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isObservable( item ) {
@@ -338,7 +342,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Checks if the item is marked as an optional.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isOptional( item ) {
@@ -355,7 +359,7 @@ module.exports = class AbstractParser {
 	 * The `internal` state means the same as `protected`, but with one exception: the `internal` member can be used from outside the class
 	 * in which it is defined (or its derivatives), as opposed to the `protected` state.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isInternal( item ) {
@@ -369,7 +373,7 @@ module.exports = class AbstractParser {
 	/**
 	 * Checks if the member is marked by the `@deprecated` JSDoc tag.
 	 *
-	 * @param {TypedocReflectionMeta>} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	isDeprecated( item ) {
@@ -387,7 +391,7 @@ module.exports = class AbstractParser {
 	 * It happens when the member has not specified `file` property. In such a case, Umberto does not know
 	 * where to point to a source and decides to skip generating the "See source" button.
 	 *
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	shouldSkipSource( item ) {
@@ -402,7 +406,7 @@ module.exports = class AbstractParser {
 	 * Returns a name specified in the `@label` annotation.
 	 *
 	 * @protected
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	_getLabelName( item ) {

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

@@ -6,21 +6,22 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class AccessorParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Accessor';
+		return item.kind === ReflectionKind.Accessor;
 	}
 
 	/**
 	 * Checks if the accessor is readonly.
 	 *
 	 * @override
-	 * @param {TypedocReflection} item
+	 * @param {AccessorReflection} item
 	 * @returns {Boolean}
 	 */
 	isReadonly( item ) {
@@ -28,7 +29,7 @@ module.exports = class AccessorParser extends AbstractParser {
 	}
 
 	/**
-	 * @param {TypedocReflection<'Accessor'>} item
+	 * @param {AccessorReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -41,6 +42,7 @@ module.exports = class AccessorParser extends AbstractParser {
 			// Needed for post-processing once all project reflections are converted.
 			_signature: [ getSignature || {}, setSignature || {} ],
 
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),
@@ -65,7 +67,7 @@ module.exports = class AccessorParser extends AbstractParser {
 	/**
 	 * Returns the access type for the item based on its signatures.
 	 *
-	 * @param {TypedocReflection<Accessor>} item
+	 * @param {AccessorReflection} item
 	 * @returns {'public'|'internal'|'protected'|'private'}
 	 */
 	getVisibilityIncludingSignature( item ) {

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

@@ -6,18 +6,19 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class ClassParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Class';
+		return item.kind === ReflectionKind.Class;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Class'>} item
+	 * @param {ClassReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -26,6 +27,7 @@ module.exports = class ClassParser extends AbstractParser {
 			// Needed for post-processing once all project reflections are converted.
 			_signature: item,
 
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),

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

@@ -6,18 +6,19 @@
 'use strict';
 
 const PropertyParser = require( './propertyparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class ComputedPropertyParser extends PropertyParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Index signature';
+		return item.kind === ReflectionKind.IndexSignature;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Index signature'>} item
+	 * @param {ComputedPropertyReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */

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

@@ -6,18 +6,19 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class ConstantParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Variable';
+		return item.kind === ReflectionKind.Variable;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Variable'>} item
+	 * @param {VariableReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -26,6 +27,7 @@ module.exports = class ConstantParser extends AbstractParser {
 			// Needed for post-processing once all project reflections are converted.
 			_signature: item,
 
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),

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

@@ -6,18 +6,19 @@
 'use strict';
 
 const MethodParser = require( './methodparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class ConstructorParser extends MethodParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Constructor';
+		return item.kind === ReflectionKind.Constructor;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Constructor'>} item
+	 * @param {ConstructorReflection} item
 	 * @param {String} parentName
 	 * @returns {Array.<Object>}
 	 */

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

@@ -9,26 +9,20 @@ const AbstractParser = require( './abstractparser' );
 
 module.exports = class ErrorParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Error';
+		return item.isCKEditor5Error === true;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Error'>} item
+	 * @param {CKEditor5ErrorReflection} item
 	 * @returns {Object}
 	 */
 	parse( item ) {
 		return {
-			_signature: [
-				{},
-				// As errors are our custom implementation, TypeDoc does not allow creating `parameters` property for them. Error parameters
-				// are passed in `typeParameters` property. To process the error parameters properly, we manually map `typeParameters` into
-				// `parameters` property.
-				{ parameters: item.typeParameters }
-			],
+			_signature: [ {}, item ],
 
 			kind: this.getKind( item ),
 			scope: 'inner',

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

@@ -9,15 +9,15 @@ const AbstractParser = require( './abstractparser' );
 
 module.exports = class EventParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Event';
+		return item.isCKEditor5Event === true;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Event'>} item
+	 * @param {CKEditor5EventReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -28,13 +28,7 @@ module.exports = class EventParser extends AbstractParser {
 
 		return {
 			// Needed for post-processing once all project reflections are converted.
-			_signature: [
-				{},
-				// As events are our custom implementation, TypeDoc does not allow creating `parameters` property for them. Event parameters
-				// are passed in `typeParameters` property. To process the event parameters properly, we manually map `typeParameters` into
-				// `parameters` property.
-				{ parameters: item.typeParameters }
-			],
+			_signature: [ {}, item ],
 
 			name: item.name,
 			memberof: parentName,

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

@@ -6,18 +6,19 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class FunctionParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Function';
+		return item.kind === ReflectionKind.Function;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Function'>} item
+	 * @param {FunctionReflection} item
 	 * @param {String} parentName
 	 * @returns {Array.<Object>}
 	 */
@@ -27,6 +28,7 @@ module.exports = class FunctionParser extends AbstractParser {
 				// Needed for post-processing once all project reflections are converted.
 				_signature: signature,
 
+				id: item.id,
 				name: item.name,
 				memberof: parentName,
 				longname: this.getLongName( item, parentName ),

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

@@ -6,18 +6,19 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class InterfaceParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Interface';
+		return item.kind === ReflectionKind.Interface;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Interface'>} item
+	 * @param {InterfaceReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
@@ -26,6 +27,7 @@ module.exports = class InterfaceParser extends AbstractParser {
 			// Needed for post-processing once all project reflections are converted.
 			_signature: item,
 
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),