umberto 5.0.2 → 6.1.0

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 Changelog
 =========
 
+## [6.1.0](https://github.com/cksource/umberto/compare/v6.0.0...v6.1.0) (2025-04-15)
+
+### Features
+
+* Added the `skipSitemap` (for ignoring generating the sitemap) and `skipThemes` (for skipping preparing assets) flags. ([commit](https://github.com/cksource/umberto/commit/8ec19222e970d2f68ace87a108ead619827124f0))
+* Ability to define a theme per project. Closes [#1242](https://github.com/cksource/umberto/issues/1242). ([commit](https://github.com/cksource/umberto/commit/3bec129a57e224f574674543d9224bda55d1e081))
+* Use the provided `mainConfig` if available when creating symlinks. ([commit](https://github.com/cksource/umberto/commit/5b61d25ff96cbc0cdce7dc5a218e1ab6ca544189))
+
+
+## [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

package/README.md

@@ -163,6 +163,8 @@ Sample documentation setup for the example above:
 `require ( 'umberto' ).buildSingleProject( options )`
 
 * `skipApi` - skip building API docs,
+* `skipSitemap` - skip building sitemap file,
+* `skipThemes` - skip building themes,
 * `skipValidation` - skip links validation,
 * `skipLivesSnippets` - skip building live code samples,
 * `snippetOptions` - options object passed to snippetAdapter building live code samples,
@@ -254,6 +256,7 @@ Every guide should have a front-matter at the top, which looks like this:
 
 ```
 ---
+layout: page [optional]
 category: builds-guides
 title: Overview [optional]
 slug: overview [optional]
@@ -338,13 +341,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 +360,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 +427,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 +441,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.2",
+  "version": "6.1.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [

package/scripts/filter/before-post-render/set-layout.js

@@ -10,19 +10,17 @@
  * page.layout indicates the template which should be used to render the page.
  */
 hexo.extend.filter.register( 'before_post_render', page => {
-	// Api index page.
+	const theme = page.projectName === 'ckeditor4' ? 'umberto' : 'gloria';
+
 	if ( page.category === 'api-reference' ) {
-		page.layout = 'api';
+		page.layout = theme + '/api';
 		page.isApi = true;
-	}
-
-	if ( page.category === 'sdk' ) {
-		page.layout = 'sdk';
+	} else if ( page.category === 'sdk' ) {
+		page.layout = theme + '/sdk';
 		page.isSdk = true;
-	}
-
-	// Main index page.
-	if ( page.path === 'index.html' ) {
-		page.layout = 'index';
+	} else if ( page.path === 'index.html' ) {
+		page.layout = theme + '/index';
+	} else {
+		page.layout = theme + '/' + page.layout;
 	}
 } );

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/api-builder/classes/doc-data-factory.js

@@ -784,7 +784,7 @@ function sorter( a, b ) {
 /**
  * This is a JavaScript version of the `renderInlineFunction()` pug mixin.
  *
- * See: themes/umberto/layout/_api-docs/_mixin/_type.pug.
+ * See: `themes/umberto/<theme name>/layout/_api-docs/_mixin/_type.pug`.
  *
  * The goal is to render an inline object describing a callable type.
  *

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

@@ -462,7 +462,7 @@ class TypeConverter {
 	 * The returned object contains a `value` property which must be an array.
 	 * Thanks to that, it can be pass through the `type()` mixin.
 	 *
-	 * See: `themes/umberto/layout/_api-docs/_mixin/_type.pug.
+	 * See: `themes/umberto/<theme name>/layout/_api-docs/_mixin/_type.pug`.
 	 *
 	 * @param {Array.<TypedocReflectionTypeParameter>|null} parameters
 	 * @returns {Array.<Object>|null}
@@ -641,7 +641,7 @@ class TypeConverter {
 		// See the `TypedocTypeDetails` type in the `typedoc.ts` file for checking the supported types.
 		//
 		// Results of this function is processed by Pug.
-		// See: `themes/umberto/layout/_api-docs/_mixin/_type.pug`.
+		// See: `themes/umberto/<theme name>/layout/_api-docs/_mixin/_type.pug`.
 		//
 		// When introducing support for more TypeScript constructions,
 		// consider introducing a new structure that contains an opening symbol,