umberto 5.0.1 → 6.0.0

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 Changelog
 =========
 
+## [6.0.0](https://github.com/cksource/umberto/compare/v5.0.2...v6.0.0) (2025-04-01)
+
+### BREAKING CHANGES
+
+* The support for cross-project links in all tags (all variants of the `@link`, `@glink` and `@icon` tags) is now dropped. In case you want to insert a link to another project, use Markdown syntax (`[link text](link target)`) or a regular HTML `<a>` tag.
+
+### Other changes
+
+* Cross-project links in `@link` (and all its variants), `@glink` and `@icon` tags are no longer supported. When detected, error message is printed in the console. Closes [#1243](https://github.com/cksource/umberto/issues/1243). ([commit](https://github.com/cksource/umberto/commit/0929fafee7e770a618496bd1ad43abac280d58c6))
+
+
+## [5.0.2](https://github.com/cksource/umberto/compare/v5.0.1...v5.0.2) (2025-03-24)
+
+### Bug fixes
+
+* Improve handling CKEditor 5 icons on the API pages. ([commit](https://github.com/cksource/umberto/commit/89f1856de2fcbd99dbdf24d17cdd05b89a08a147))
+
+
 ## [5.0.1](https://github.com/cksource/umberto/compare/v5.0.0...v5.0.1) (2025-03-13)
 
 Internal changes only (updated dependencies, documentation, etc.).

package/README.md

@@ -338,13 +338,13 @@ Tags are strings which can be used in guides and are replaced by Umberto with ge
 Syntax:
 
 ```
-{@link @projectName longname linkText}
+{@link longname linkText}
 ```
 
 Example:
 
 ```
-{@link @ckeditor5 module:ui/template~Template#render Render method}
+{@link module:ui/template~Template#render Render method}
 ```
 
 **Note:** If `longname` doesn't start with `module:`, please use `@linkapi` instead of `@link`.
@@ -357,9 +357,7 @@ Example links for CKEditor 4:
 
 `{@linkapi CKEDITOR.dialog.definition#resizable resizable}` -> https://docs.ckeditor.com/ckeditor4/latest/api/CKEDITOR_dialog_definition.html#resizable
 
-##### @projectName
-
-It is optional and must be used only if creating a link to other project's API (in case of a multi-project documentation).
+**Important:** Cross-project links `{@link @projectName longname linkText}` are no longer supported.
 
 ##### longname
 
@@ -426,28 +424,12 @@ A link to https://github.com/ckeditor/ckeditor5/blob/master/docs/builds/guides/o
 {@link builds/guides/overview Builds overview}
 ```
 
-In order to link to a guide of another project please follow this syntax:
-
-```
-{@link @projectslug pathToGuide linkText}
-```
-
-where `@projectslug` is the slug of another project and can be find in the project's `umberto.json`
-
-Example:
-
-```
-{@link @letters index Home page of Letters}
-```
-
 **Note:** It is possible to link to a guide from a JSDoc comment using `{@glink}` tag (so that Umberto can distinguish it from a regular JSDoc's `{@link}` tag):
 
 ```
-{@glink @projectSlug finalPathToGuide linkText}
+{@glink finalPathToGuide linkText}
 ```
 
-where `@projectslug` is the slug of another project and can be find in the project's `umberto.json`. This parameter is optional.
-
 **Important:** In this case `finalPathToGuide` **must be** a guide's final URL. Final URL may be different than guide's physical path (usually it's the same though)
 
 Example:
@@ -456,6 +438,8 @@ Example:
 {@glink builds/guides/migrate Migration guide}
 ```
 
+**Important:** Cross-project links (`{@link @projectName pathToGuide linkText}` or `{@glink @projectName finalPathToGuide linkText}`) are no longer supported.
+
 #### Links escaping
 
 Umberto allows on link escaping, when curly brackets are preceed with backslash.

package/package.json

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

package/scripts/utils/logcrossprojectreference.js

@@ -0,0 +1,29 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const chalk = require( 'chalk' );
+
+/**
+ * Logs an error message about a cross-project reference found in the parsed expression.
+ * See: https://github.com/cksource/umberto/issues/1243.
+ *
+ * @param {Object} data
+ * @param {String} data.expression
+ * @param {String} [data.source]
+ * @returns {String}
+ */
+module.exports = function logCrossProjectReference( { expression, source } ) {
+	process.exitCode = 1;
+
+	const message = `${ chalk.red( 'Error:' ) } Failed while convert ${ chalk.cyanBright( expression ) } tag`;
+	const messageLocation = source ? ` in ${ chalk.magentaBright( source ) }.` : '.';
+	const messageDescription = ' Cross-project references are not supported.';
+
+	console.log( message + messageLocation + messageDescription );
+
+	return expression;
+};

package/scripts/utils/parseicontag.js

@@ -7,6 +7,7 @@
 
 const crypto = require( 'crypto' );
 const upath = require( 'upath' );
+const logCrossProjectReference = require( './logcrossprojectreference' );
 
 const ICON_REGEXP = /\\?{@icon(?:\s+@(\w+))?\s+([^}\s]+)\s*([^}]*)\\?}/g;
 
@@ -21,26 +22,18 @@ const ICON_REGEXP = /\\?{@icon(?:\s+@(\w+))?\s+([^}\s]+)\s*([^}]*)\\?}/g;
  */
 module.exports = function parseIconTag( page, hexo ) {
 	const relativeUrlHelper = hexo.extend.helper.store.relative_url;
-	const availableProjects = Object.keys( hexo.projectGlobals ).filter( projectName => projectName !== 'common' );
 
 	page.content = page.content.replace( ICON_REGEXP, ( match, iconProject, iconPath, alternativeText ) => {
-		const options = {
-			isSingleProject: hexo.projectGlobals.common.isSingleProject,
-			pageProject: page.projectName,
-			iconProject,
-			availableProjects
-		};
-
-		if ( !shouldTransformIcon( options ) ) {
-			return match;
+		// Cross project references are not supported.
+		if ( iconProject ) {
+			return logCrossProjectReference( { expression: match, source: page.source } );
 		}
 
 		if ( match.startsWith( '\\{' ) ) {
 			return match.replace( /^\\{/, '{' ).replace( /\\}$/, '}' );
 		}
 
-		const projectName = iconProject || page.projectName;
-		const projectDetails = hexo.projectGlobals[ projectName ];
+		const projectDetails = hexo.projectGlobals[ page.projectName ];
 		const fileName = sha1( iconPath ).substr( 0, 10 ) + upath.extname( iconPath );
 
 		// Map the original file name with the hashed version to predict the path when copying assets.
@@ -52,7 +45,7 @@ module.exports = function parseIconTag( page, hexo ) {
 			alt = `alt="${ alternativeText }" `;
 		}
 
-		const absoluteLikePath = upath.join( projectName, projectDetails.config.version, 'assets', 'icons', fileName );
+		const absoluteLikePath = upath.join( page.projectName, projectDetails.config.version, 'assets', 'icons', fileName );
 
 		return [
 			'<span class="editor-icon">' +
@@ -64,36 +57,6 @@ module.exports = function parseIconTag( page, hexo ) {
 	return page;
 };
 
-/**
- * Checks whether the `{@icon}` expression should be transformed to proper `<img>` tag.
- *
- * @param {Object} options
- * @param {Boolean} options.isSingleProject Whether building for a single project.
- * @param {String} options.pageProject The project of the current processed page.
- * @param {String} options.iconProject The project specified in the `{@icon}` expression.
- * @param {Array.<String>} options.availableProjects Available projects when building the non-single project documentation.
- * @return {Boolean}
- */
-function shouldTransformIcon( options ) {
-	// {@icon path} - missing the @projectName part.
-	// Assuming, that loading an icon for the page's project.
-	if ( !options.iconProject ) {
-		return true;
-	}
-
-	// Building a page that belongs to the same project as specified in the icon.
-	if ( options.iconProject === options.pageProject ) {
-		return true;
-	}
-
-	// Building many projects. Check whether the project exists.
-	if ( !options.isSingleProject && options.availableProjects.includes( options.iconProject ) ) {
-		return true;
-	}
-
-	return false;
-}
-
 /**
  * @param {String} value
  * @return {String}

package/scripts/utils/parselinks.js

@@ -13,6 +13,7 @@ const LINK_REGEXP = /\\?{(?:@linkapi|@link|@linksdk|@linkexample)\s+[^{]+?({[^}]
 
 const findTargetDoclet = require( '../../src/api-builder/utils/findtargetdoclet' );
 const { hasDedicatedApiPages, LONG_NAME_LABEL_REGEXP } = require( '../../src/api-builder/utils/utils' );
+const logCrossProjectReference = require( './logcrossprojectreference' );
 
 /**
  * Converts @link or @linkapi tags into working links to guides or API docs.
@@ -70,7 +71,13 @@ function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 		} );
 	}
 
-	const projectName = linkContentMatchResult[ 1 ] || data.projectName;
+	const projectName = linkContentMatchResult[ 1 ];
+
+	// Cross project references are not supported.
+	if ( projectName ) {
+		return logCrossProjectReference( { expression: str, source: data.source } );
+	}
+
 	const { name, label } = splitLongname( linkContentMatchResult[ 2 ] );
 	const itemName = linkContentMatchResult[ 2 ].replace( LONG_NAME_LABEL_REGEXP, '' );
 	let linkText = linkContentMatchResult[ 3 ] || name;
@@ -92,7 +99,7 @@ function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 	const baseItemName = getBaseItemName( itemName );
 	let hashWithoutPrefix = itemName.replace( baseItemName, '' ).slice( 1 );
 	const hash = hashWithoutPrefix ? `#${ hashWithoutPrefix }` : '';
-	const project = hexo.projectGlobals[ projectName ];
+	const project = hexo.projectGlobals[ data.projectName ];
 
 	if ( hashWithoutPrefix.includes( '-' ) ) {
 		let [ type, description ] = hashWithoutPrefix.split( '-' );
@@ -113,18 +120,18 @@ function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 
 	if ( project && project.config ) {
 		apiSlug = getSlug( project.config, 'api-reference' ) || 'api-reference';
-	} else if ( isIgnoredProject( projectName, hexo ) || hexo.projectGlobals.common.isSingleProject ) {
+	} else if ( isIgnoredProject( data.projectName, hexo ) || hexo.projectGlobals.common.isSingleProject ) {
 		return str;
 	} else {
 		return onError( {
 			value: str,
 			source: data.source,
 			isSilent: isSilentError,
-			description: `Project ${ chalk.redBright( projectName ) } is not defined.`
+			description: `Project ${ chalk.redBright( data.projectName ) } is not defined.`
 		} );
 	}
 
-	const basePath = projectName === data.projectName ? data.BASE_PATH : `${ projectName }/latest`;
+	const basePath = data.BASE_PATH;
 	const fileName = getFileName( baseItemName );
 
 	let href = relativeUrlHelper( data.path, upath.join( basePath, apiSlug, fileName + hash ) );
@@ -236,9 +243,15 @@ function linkToSdk( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 		} );
 	}
 
-	const projectName = match[ 1 ] ? match[ 1 ] : data.projectName;
-	const sdkSlug = getSlug( hexo.projectGlobals[ projectName ].config, 'sdk' );
-	const basePath = projectName === data.projectName ? data.BASE_PATH : `${ projectName }/latest`;
+	const projectName = match[ 1 ];
+
+	// Cross project references are not supported.
+	if ( projectName ) {
+		return logCrossProjectReference( { expression: str, source: data.source } );
+	}
+
+	const sdkSlug = getSlug( hexo.projectGlobals[ data.projectName ].config, 'sdk' );
+	const basePath = data.BASE_PATH;
 	const sdkFileName = match[ 2 ];
 	const sdkFileHash = match[ 3 ] || '';
 	const sdkLinkName = match[ 4 ];
@@ -271,23 +284,15 @@ function linkToGuide( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 	const pathToGuide = pathToGuideSplit[ 0 ];
 	const hash = pathToGuideSplit.length > 1 ? `#${ pathToGuideSplit[ 1 ] }` : '';
 	const linkText = match[ 3 ] ? match[ 3 ] : pathToGuide;
-	const projectName = match[ 1 ] ? match[ 1 ] : data.projectName;
-	const pagePaths = hexo.projectGlobals[ projectName ] ? hexo.projectGlobals[ projectName ].pagePaths : null;
+	const projectName = match[ 1 ];
 
-	if ( shouldIgnoreGuideLink( match, data, projectName, hexo ) ) {
-		if ( isIgnoredProject( projectName, hexo ) || hexo.projectGlobals.common.isSingleProject ) {
-			return str;
-		}
-
-		return onError( {
-			value: str,
-			source: data.source,
-			isSilent: isSilentError,
-			description: `Project ${ chalk.redBright( projectName ) } is not defined.`
-		} );
+	// Cross project references are not supported.
+	if ( projectName ) {
+		return logCrossProjectReference( { expression: str, source: data.source } );
 	}
 
-	const projectBasePath = match[ 1 ] ? hexo.projectGlobals[ projectName ].BASE_PATH : data.BASE_PATH;
+	const pagePaths = hexo.projectGlobals[ data.projectName ] ? hexo.projectGlobals[ data.projectName ].pagePaths : null;
+	const projectBasePath = data.BASE_PATH;
 
 	let targetPath;
 
@@ -360,29 +365,3 @@ function getSlug( config, name ) {
 
 	return null;
 }
-
-/**
- * When linking to an external project and the documentation is being built for a single project, the link should remain untouched.
- *
- * However, if the link points to the same project, let's transform it. See #914.
- *
- * @param {Object} match
- * @param {Object} page
- * @param {String} projectName
- * @param {Object} hexo
- * @return {Boolean}
- */
-function shouldIgnoreGuideLink( match, page, projectName, hexo ) {
-	// If the project `{@link @projectName ...}` is not specified, the URL should be transformed.
-	if ( !match[ 1 ] ) {
-		return false;
-	}
-
-	// Also, if the `page` belongs to the same project as `@projectName`, the link should be transformed.
-	if ( match[ 1 ] === page.projectName ) {
-		return false;
-	}
-
-	// Building the single project or the project does not exist. Do not transform links.
-	return ( hexo.projectGlobals.common.isSingleProject || !hexo.projectGlobals[ projectName ] );
-}

package/src/api-builder/classes/description-parser.js

@@ -11,6 +11,7 @@ const chalk = require( 'chalk' );
 const macroReplacer = require( '../../tasks/macro-replacer' );
 const findTargetDoclet = require( '../utils/findtargetdoclet' );
 const { hasDedicatedApiPages, LONG_NAME_LABEL_REGEXP, LONG_NAME_MEMBER_SEPARATOR_REGEXP } = require( '../utils/utils' );
+const logCrossProjectReference = require( '../../../scripts/utils/logcrossprojectreference' );
 
 /**
  * Class responsible for parsing doc descriptions.
@@ -83,20 +84,27 @@ module.exports = class DescriptionParser {
 			return result;
 		}
 
-		let match = guideLinkRegExp.exec( str );
+		let match;
 
-		while ( match !== null ) {
+		while ( ( match = guideLinkRegExp.exec( str ) ) !== null ) {
 			const detailedRegExp = /@glink\s+(?:@(\w+)\s+)?([^}\s]+)\s*([^}]*)}/;
 			const detailedMatch = detailedRegExp.exec( match[ 0 ] );
-			const projectSlug = detailedMatch[ 1 ] ? detailedMatch[ 1 ] : null;
+			const projectSlug = detailedMatch[ 1 ];
+
+			// Cross project references are not supported.
+			if ( projectSlug ) {
+				logCrossProjectReference( { expression: match[ 0 ] } );
+
+				continue;
+			}
+
 			const pathToGuideSplit = detailedMatch[ 2 ].split( '#' );
 			const pathToGuide = pathToGuideSplit[ 0 ];
 			const hash = pathToGuideSplit.length > 1 ? `#${ pathToGuideSplit[ 1 ] }` : '';
 			const linkText = detailedMatch[ 3 ] ? detailedMatch[ 3 ] : pathToGuide;
-			const href = projectSlug ? `../../../${ projectSlug }/latest/${ pathToGuide }.html` : `../${ pathToGuide }.html`;
+			const href = `../${ pathToGuide }.html`;
 
 			result = result.replace( match[ 0 ], `<a href=${ href }${ hash } data-glink>${ linkText }</a>` );
-			match = guideLinkRegExp.exec( str );
 		}
 
 		return result;

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

@@ -172,6 +172,25 @@ class TypedocConverter {
 	 * @param {String|null} [parentName=null]
 	 */
 	_convertChild( reflection, parentName = null ) {
+		// For unknown reasons, TypeScript or TypeDoc treats all CKEditor 5 icons (except for the first one)
+		// as a reference to the first exported member by a module.
+		// We map them manually to display a proper list of the available doclets.
+		// See: https://github.com/cksource/ckeditor5-internal/issues/3993.
+		if ( parentName === 'module:icons/index' && reflection.kindString === 'Reference' ) {
+			reflection = {
+				...reflection,
+				kind: 32,
+				kindString: 'Variable',
+				flags: {
+					isConst: true
+				},
+				type: {
+					type: 'intrinsic',
+					name: 'string'
+				}
+			};
+		}
+
 		const parser = this._parsers.find( parser => parser.canParse( reflection ) );
 
 		let doclets;

package/themes/umberto/src/js/app.js

@@ -28,7 +28,6 @@ import showWarningBanner from './_warningbanner';
 import { enableBadgeTooltips, createTooltip } from './_tooltips';
 import attachPermalinkListener from './_attachpermalinklistener';
 import { createCodeSwitcherButtons } from './_codeswitcherbuttons';
-import { sendUserDate } from './_sendUserDate';
 
 // Changing documentation theme. To enable, type in the console: `localStorage.setItem( 'theme', 'theme-dark' )`.
 if ( localStorage.getItem( 'theme' ) === 'theme-dark' ) {
@@ -68,5 +67,4 @@ $( document ).ready( () => {
 	sampleCode(); // control accordion of sample code and buttons(copy/download)
 	enableBadgeTooltips(); // attaches tippy.js tooltip for all elements with data-badge-tooltip
 	createCodeSwitcherButtons();
-	sendUserDate();
 } );

package/themes/umberto/src/js/_sendUserDate.js

@@ -1,54 +0,0 @@
-/**
- * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-const IS_USER_DATE_SENT_KEY = 'is_local_user_os_date_sent';
-const STATS_EVENT_URL_DEV = 'https://builder-api.internal.cke-cs-dev.com/events';
-const STATS_EVENT_URL_PROD = 'https://builder-api.ckeditor.com/events';
-
-export function sendUserDate() {
-	const isUserDateSent = localStorage.getItem( IS_USER_DATE_SENT_KEY );
-	const environment = getEnvironment();
-	const isProdOrNightly = environment === 'production' || environment === 'nightly';
-	const userDateUrl = isProdOrNightly ? STATS_EVENT_URL_PROD : STATS_EVENT_URL_DEV;
-
-	if ( isUserDateSent ) {
-		// User date info is already collected. Aborting.
-		return;
-	}
-
-	fetch( userDateUrl, {
-		method: 'POST',
-		headers: {
-			'Content-Type': 'application/json'
-		},
-		body: JSON.stringify( {
-			environment,
-			event_type: 'cksource_docs_date',
-			event_data: {
-				date: new Date().toISOString(),
-				user_agent: window.navigator.userAgent,
-				language: window.navigator.language
-			}
-		} )
-	} ).then( () => {
-		localStorage.setItem( IS_USER_DATE_SENT_KEY, 'true' );
-	} ).catch( () => {
-		// There is no need to report if sending user date fails.
-	} );
-}
-
-function getEnvironment() {
-	const hostname = window.location.hostname;
-
-	if ( hostname.startsWith( 'ckeditor5.github.io' ) ) {
-		return 'nightly';
-	}
-
-	if ( hostname.startsWith( 'ckeditor.com' ) ) {
-		return 'production';
-	}
-
-	return 'local';
-}