umberto 9.4.0 → 10.0.0

package/src/helpers/github-url.js

@@ -3,115 +3,108 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { spawnSync } = require( 'node:child_process' );
-const upath = require( 'upath' );
+import { spawnSync } from 'node:child_process';
+import upath from 'upath';
 
 const cachedGitPaths = new Set();
 const gitHashCache = new Map();
 
-const utils = {
-	/**
-	 * Returns a URL where a user will be redirect after clicking a "Report new issue" button.
-	 *
-	 * @param {Object} projectConfig
-	 * @param {String} [projectConfig.issueUrl] An absolute URL for reporting an issue. If specified, it will be used.
-	 * @param {String} [projectConfig.repoUrlDocs] An absolute URL where the repository is located.
-	 * @returns {String}
-	 */
-	getIssueUrl( projectConfig ) {
-		const reportIssueRepository = projectConfig.issueUrl || projectConfig.repoUrlDocs;
-
-		if ( !reportIssueRepository ) {
-			return '';
-		}
-
-		return `${ reportIssueRepository }/issues/new`;
-	},
-
-	/**
-	 * Returns a URL where a user will be redirect after clicking a "Contribute to this guide" button.
-	 *
-	 * @param {Object} projectConfig
-	 * @param {String} [projectConfig.contributeUrl] An absolute URL for contributing to the guide.
-	 * @param {String} [projectConfig.repoUrlDocs] An absolute URL where the repository is located.
-	 * @param {Boolean} [projectConfig.doNotAddDocsInPath=false] If set to true, `docs/` part won't be added to the URL.
-	 * @param {String} sourceDirOrPathKey If `pathKey` was passed, `itemName` is not required. The `pathKey` part contains
-	 * the rest of path to the page (including an extension). `sourceDir` is a directory where the entire SDK group is located.
-	 * @param {String|null} [itemName=null] Name of the guide where the URL should be generated. Required if `sourceDirOrPathKey`
-	 * contains the `sourceDir` for specified SDK group. In such case, `itemName` is a name from SDK item that belongs to given group.
-	 * @returns {String}
-	 */
-	getContributeUrl( projectConfig, sourceDirOrPathKey, itemName = null ) {
-		const contributeRepository = projectConfig.contributeUrl || projectConfig.repoUrlDocs;
-
-		if ( !contributeRepository ) {
-			return '';
-		}
-
-		const urlParts = [
-			contributeRepository,
-			'blob',
-			'master'
-		];
-
-		if ( !projectConfig.doNotAddDocsInPath ) {
-			urlParts.push( 'docs' );
-		}
-
-		urlParts.push( sourceDirOrPathKey.replace( /^\//, '' ) );
-
-		if ( itemName ) {
-			urlParts.push( itemName + '.html' );
-		}
-
-		return urlParts.join( '/' );
-	},
-
-	/**
-	 * Method obtain URL string with repository address including hash of github repository which was used to build given docs files.
-	 *
-	 * @param {String} repoUrl Repository url for which we need to obtain full url to github
-	 * @param {Object} file Object storing details about given documentation entry
-	 * @param {String} file.filePath Path to file where documentation was read
-	 * @param {Number} file.lineNr Line number where documentation starts
-	 * @param {Number} file.len Length of comment
-	 *
-	 * @returns {String/null} String URL to github with specific hash and line numbers to highlight
-	 */
-	getFullGithubLink( repoUrl, file ) {
-		const filePath = file.filePath;
-
-		let projectName;
-
-		// TODO: Couldn't be the repository/github link obtained based on the file path?
-		// We know where the file is saved. Based on that, we could find the repository URL
-		// and adjust values.
-		if ( repoUrl.startsWith( '@ckeditor' ) ) {
-			projectName = filePath.match( /([^(?:/|\\)]+)(?:\/|\\)packages/ )[ 1 ];
-		} else {
-			projectName = repoUrl.replace( /\/*$/, '' ).match( /[^/]*$/ )[ 0 ];
-		}
-
-		const pathSuffix = _getPathSuffix( filePath );
-
-		if ( !pathSuffix ) {
-			return null;
-		}
-
-		const gitHash = _getGitHashFromPath( filePath.replace( pathSuffix, '' ) );
-
-		if ( !gitHash ) {
-			return null;
-		}
-
-		// eslint-disable-next-line @stylistic/max-len
-		return `https://github.com/ckeditor/${ projectName }/blob/${ gitHash }${ pathSuffix }#L${ file.lineNr }-L${ file.lineNr + file.len }`;
+/**
+ * Returns a URL where a user will be redirect after clicking a "Report new issue" button.
+ *
+ * @param {Object} projectConfig
+ * @param {String} [projectConfig.issueUrl] An absolute URL for reporting an issue. If specified, it will be used.
+ * @param {String} [projectConfig.repoUrlDocs] An absolute URL where the repository is located.
+ * @returns {String}
+ */
+export function getIssueUrl( projectConfig ) {
+	const reportIssueRepository = projectConfig.issueUrl || projectConfig.repoUrlDocs;
+
+	if ( !reportIssueRepository ) {
+		return '';
+	}
+
+	return `${ reportIssueRepository }/issues/new`;
+}
+
+/**
+ * Returns a URL where a user will be redirect after clicking a "Contribute to this guide" button.
+ *
+ * @param {Object} projectConfig
+ * @param {String} [projectConfig.contributeUrl] An absolute URL for contributing to the guide.
+ * @param {String} [projectConfig.repoUrlDocs] An absolute URL where the repository is located.
+ * @param {Boolean} [projectConfig.doNotAddDocsInPath=false] If set to true, `docs/` part won't be added to the URL.
+ * @param {String} sourceDirOrPathKey If `pathKey` was passed, `itemName` is not required. The `pathKey` part contains
+ * the rest of path to the page (including an extension). `sourceDir` is a directory where the entire SDK group is located.
+ * @param {String|null} [itemName=null] Name of the guide where the URL should be generated. Required if `sourceDirOrPathKey`
+ * contains the `sourceDir` for specified SDK group. In such case, `itemName` is a name from SDK item that belongs to given group.
+ * @returns {String}
+ */
+export function getContributeUrl( projectConfig, sourceDirOrPathKey, itemName = null ) {
+	const contributeRepository = projectConfig.contributeUrl || projectConfig.repoUrlDocs;
+
+	if ( !contributeRepository ) {
+		return '';
+	}
+
+	const urlParts = [
+		contributeRepository,
+		'blob',
+		'master'
+	];
+
+	if ( !projectConfig.doNotAddDocsInPath ) {
+		urlParts.push( 'docs' );
+	}
+
+	urlParts.push( sourceDirOrPathKey.replace( /^\//, '' ) );
+
+	if ( itemName ) {
+		urlParts.push( itemName + '.html' );
+	}
+
+	return urlParts.join( '/' );
+}
+
+/**
+ * Method obtain URL string with repository address including hash of github repository which was used to build given docs files.
+ *
+ * @param {String} repoUrl Repository url for which we need to obtain full url to github
+ * @param {Object} file Object storing details about given documentation entry
+ * @param {String} file.filePath Path to file where documentation was read
+ * @param {Number} file.lineNr Line number where documentation starts
+ * @param {Number} file.len Length of comment
+ *
+ * @returns {String/null} String URL to github with specific hash and line numbers to highlight
+ */
+export function getFullGithubLink( repoUrl, file ) {
+	const filePath = file.filePath;
+
+	let projectName;
+
+	// TODO: Couldn't be the repository/github link obtained based on the file path?
+	// We know where the file is saved. Based on that, we could find the repository URL
+	// and adjust values.
+	if ( repoUrl.startsWith( '@ckeditor' ) ) {
+		projectName = filePath.match( /([^(?:/|\\)]+)(?:\/|\\)packages/ )[ 1 ];
+	} else {
+		projectName = repoUrl.replace( /\/*$/, '' ).match( /[^/]*$/ )[ 0 ];
 	}
-};
 
-module.exports = utils;
+	const pathSuffix = _getPathSuffix( filePath );
+
+	if ( !pathSuffix ) {
+		return null;
+	}
+
+	const gitHash = _getGitHashFromPath( filePath.replace( pathSuffix, '' ) );
+
+	if ( !gitHash ) {
+		return null;
+	}
+
+	return `https://github.com/ckeditor/${ projectName }/blob/${ gitHash }${ pathSuffix }#L${ file.lineNr }-L${ file.lineNr + file.len }`;
+}
 
 function _getPathSuffix( fileInGitRepositoryPath ) {
 	const searchedGitPath = [ ...cachedGitPaths ].find( gitPath => fileInGitRepositoryPath.startsWith( gitPath ) );

package/src/helpers/glob-to-regexp.js

@@ -3,9 +3,7 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const escapeStringRegexp = require( 'escape-string-regexp' );
+import escapeStringRegexp from 'escape-string-regexp';
 
 /**
  * Converts the specified `pattern` to an instance of RegExp.
@@ -13,8 +11,8 @@ const escapeStringRegexp = require( 'escape-string-regexp' );
  * @param {String} pattern
  * @return {RegExp}
  */
-module.exports = function globToRegexp( pattern ) {
+export function globToRegexp( pattern ) {
 	return new RegExp(
 		escapeStringRegexp( pattern ).replace( /\\\*/g, '[\\s\\S]*' ).replace( /\//g, '[\\\\/]' )
 	);
-};
+}

package/src/helpers/html-safe.js

@@ -3,14 +3,12 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
 /**
  * Escapes string
  * @param str
  * @returns {String}
  */
-module.exports = str => {
+export const htmlSafe = str => {
 	if ( typeof str !== 'string' ) {
 		str = String( str );
 	}

package/src/helpers/import-module.js

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const upath = require( 'upath' );
-const { pathToFileURL } = require( 'node:url' );
+import upath from 'upath';
+import { pathToFileURL } from 'node:url';
 
 /**
  * Loads the specified module using `import()` call.
@@ -14,7 +12,7 @@ const { pathToFileURL } = require( 'node:url' );
  * @param {String} modulePath
  * @returns {Promise.<Function>}
  */
-module.exports = async function importModule( modulePath ) {
+export async function importModule( modulePath ) {
 	const modulePathAsFileURL = getPathAsFileURL( modulePath );
 
 	return ( await import( modulePathAsFileURL ) ).default;

package/src/helpers/is-non-empty-array.js

@@ -3,13 +3,11 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
 /**
  * Checks if value is a non-empty Array.
  * @param arr
  * @returns {boolean}
  */
-module.exports = arr => {
+export const isNonEmptyArray = arr => {
 	return Array.isArray( arr ) && arr.length > 0;
 };

package/src/helpers/log-with-time.js

@@ -3,11 +3,9 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+import { styleText } from 'node:util';
 
-const { styleText } = require( 'node:util' );
-
-module.exports = function logWithTime( message ) {
+export function logWithTime( message ) {
 	const lowercase = message.charAt( 0 ).toLowerCase() + message.slice( 1 );
 	const getTime = measureSeconds();
 

package/src/helpers/resolve-path.js

@@ -3,11 +3,13 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire( import.meta.url );
 
 /**
  * Wrapper around `require.resolve()` to allow mocking it in tests.
  */
-module.exports = function resolvePath( path, options ) {
+export function resolvePath( path, options ) {
 	return require.resolve( path, options );
-};
+}

package/src/helpers/snippets.js

@@ -3,61 +3,55 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const upath = require( 'upath' );
-const { globSync } = require( 'glob' );
-
-const utils = {
-	/**
-	 * Checks whether snippets should be built for specified `projectName`.
-	 *
-	 * @param {String} projectName Current parsed project name.
-	 * @param {Object} hexo Options come from Hexo.
-	 * @returns {Boolean}
-	 */
-	shouldBuildSnippets( projectName, hexo ) {
-		if ( !hexo.projectGlobals || !hexo.projectGlobals[ projectName ] ) {
-			return false;
-		}
-
-		if ( hexo.projectGlobals.common && hexo.projectGlobals.common.skipLiveSnippets ) {
-			return false;
-		}
-
-		return true;
-	},
-
-	/**
-	 * Returns all files that are required for building the snippet.
-	 *
-	 * @param {String} basePath An absolute path where the snippets are saved.
-	 * @param {String} snippetName A name of the snippet which files are being looked for.
-	 * @returns {SnippetSource}
-	 */
-	getSnippetSourcePaths( basePath, snippetName ) {
-		const files = {};
-
-		globSync( upath.join( basePath, snippetName + '.*' ) )
-			.map( path => upath.normalize( path ) )
-			.forEach( singlePath => {
-				const fileExtension = upath.extname( singlePath ).slice( 1 );
-
-				files[ fileExtension ] = singlePath;
-			} );
-
-		return files;
-	},
-
-	/**
-	 * Returns a HTML Comment Node that will be replaced with the proper snippet later.
-	 *
-	 * @param {String} snippetName
-	 * @returns {String}
-	 */
-	getSnippetPlaceholder( snippetName ) {
-		return `<!--UMBERTO: SNIPPET: "${ snippetName }"-->`;
+import upath from 'upath';
+import { globSync } from 'glob';
+
+/**
+ * Checks whether snippets should be built for specified `projectName`.
+ *
+ * @param {String} projectName Current parsed project name.
+ * @param {Object} hexo Options come from Hexo.
+ * @returns {Boolean}
+ */
+export function shouldBuildSnippets( projectName, hexo ) {
+	if ( !hexo.projectGlobals || !hexo.projectGlobals[ projectName ] ) {
+		return false;
 	}
-};
 
-module.exports = utils;
+	if ( hexo.projectGlobals.common && hexo.projectGlobals.common.skipLiveSnippets ) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Returns all files that are required for building the snippet.
+ *
+ * @param {String} basePath An absolute path where the snippets are saved.
+ * @param {String} snippetName A name of the snippet which files are being looked for.
+ * @returns {SnippetSource}
+ */
+export function getSnippetSourcePaths( basePath, snippetName ) {
+	const files = {};
+
+	globSync( upath.join( basePath, snippetName + '.*' ) )
+		.map( path => upath.normalize( path ) )
+		.forEach( singlePath => {
+			const fileExtension = upath.extname( singlePath ).slice( 1 );
+
+			files[ fileExtension ] = singlePath;
+		} );
+
+	return files;
+}
+
+/**
+ * Returns a HTML Comment Node that will be replaced with the proper snippet later.
+ *
+ * @param {String} snippetName
+ * @returns {String}
+ */
+export function getSnippetPlaceholder( snippetName ) {
+	return `<!--UMBERTO: SNIPPET: "${ snippetName }"-->`;
+}

package/src/helpers/split-longname.js

@@ -3,15 +3,13 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { MEMBER_NAME_REGEXP, LONG_NAME_LABEL_REGEXP } = require( '../api-builder/utils/utils' );
+import { MEMBER_NAME_REGEXP, LONG_NAME_LABEL_REGEXP } from '../api-builder/utils/utils.js';
 
 /**
  * @param {String} longname
  * @returns {LongNameParts}
  */
-module.exports = longname => {
+export const splitLongname = longname => {
 	if ( !longname || typeof longname !== 'string' ) {
 		return {};
 	}

package/src/helpers/umberto-version.js

@@ -0,0 +1,10 @@
+/**
+ * @license Copyright (c) 2017-2026, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import fs from 'node:fs';
+
+const umbertoPackage = JSON.parse( fs.readFileSync( new URL( '../../package.json', import.meta.url ), 'utf8' ) );
+
+export const umbertoVersion = umbertoPackage.version;

package/src/hexo/filter/extend-config.js

@@ -3,9 +3,7 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-module.exports = ( ctx, customConfig ) => {
+export const extendConfig = ( ctx, customConfig ) => {
 	ctx.extend.filter.register( 'after_init', () => {
 		ctx.config = Object.assign( ctx.config, customConfig );
 		// jscs:disable

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

@@ -3,12 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const upath = require( 'upath' );
-const getPageGroupHelper = require( '../helper/get-page-group' );
-const getDocSearchConfig = require( '../../helpers/get-docsearch-config' );
-const umbertoVersion = require( '../../../package.json' ).version;
+import upath from 'upath';
+import { getPageGroup as getPageGroupHelper } from '../helper/get-page-group.js';
+import { getDocsearchConfig as getDocSearchConfig } from '../../helpers/get-docsearch-config.js';
+import { umbertoVersion } from '../../helpers/umberto-version.js';
 
 /**
  * Resolves the API package name from a docs path.
@@ -92,7 +90,7 @@ function getApiTreeHtml( { path, basePath, apiSlug, navTree, navTreeByPackage }
  * @param {Boolean} navigationShowEmptyCategories If set on true, empty categories will be displayed.
  * @param {Object} og Open Graph config.
  */
-module.exports = ( ctx, {
+export const projectLocals = ( ctx, {
 	basePath,
 	docSearch = {},
 	config,

package/src/hexo/get-repo-urls.js

@@ -3,12 +3,11 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+import fs from 'node:fs';
+import upath from 'upath';
+import { globSync } from 'glob';
 
-const upath = require( 'upath' );
-const { globSync } = require( 'glob' );
-
-module.exports = ( {
+export const getRepoUrls = ( {
 	rootPath,
 	defaultRepoUrl,
 	packages = []
@@ -54,7 +53,7 @@ function getPackageJson( srcDir ) {
 	let packageJson = null;
 
 	try {
-		packageJson = require( upath.join( srcDir, 'package.json' ) );
+		packageJson = JSON.parse( fs.readFileSync( upath.join( srcDir, 'package.json' ), 'utf8' ) );
 	} catch {
 		console.warn( `Warning: Cannot read package.json from ${ srcDir }.` );
 	}

package/src/hexo/helper/get-page-group.js

@@ -3,9 +3,7 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-module.exports = groups => {
+export const getPageGroup = groups => {
 	return function( groupId ) {
 		return groups.find( g => g.id === groupId );
 	};

package/src/hexo/project-globals.js

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const upath = require( 'upath' );
-const getRepoUrls = require( './get-repo-urls' );
+import upath from 'upath';
+import { getRepoUrls } from './get-repo-urls.js';
 
 /**
  * Adds various project data to hexo so that it can be accessed in filters.
@@ -17,7 +15,7 @@ const getRepoUrls = require( './get-repo-urls' );
  * @param {Object} config Project's umberto.json config.
  * @param {String} errorsHtml API errors HTML created by ApiBuilder.
  */
-module.exports = ( ctx, {
+export const projectGlobals = ( ctx, {
 	rootPath,
 	basePath,
 	config,
@@ -42,7 +40,7 @@ module.exports = ( ctx, {
 		errorsHtml,
 
 		// The `_icons` collection contains files that should be copied to the project's assets.
-		// They are parsed in the `parseIconTag()` function. See `scripts/filter/after-post-render/parseicontag.js`.
+		// They are parsed in the `parseIconTag()` function. See `scripts/filter/after-post-render/parseicontag.cjs`.
 		_icons: new Map()
 	};
 

package/src/hexo-manager.js

@@ -3,16 +3,15 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+import { styleText } from 'node:util';
+import upath from 'upath';
+import fs from 'fs-extra';
+import { globSync } from 'glob';
+import Hexo from '../hexo-shim.js';
+import { getHexoConfig } from './tasks/get-hexo-config.js';
+import { extendConfig } from './hexo/filter/extend-config.js';
 
-const { styleText } = require( 'node:util' );
-const upath = require( 'upath' );
-const fs = require( 'fs-extra' );
-const { globSync } = require( 'glob' );
-const Hexo = require( '../hexo-shim' );
-
-const getHexoConfig = require( './tasks/get-hexo-config' );
-const extendConfig = require( './hexo/filter/extend-config' );
+const __dirname = import.meta.dirname;
 
 /**
  * Class used to initialize and control hexo.
@@ -198,18 +197,18 @@ class HexoManager {
 
 			Object.assign( this.hexo.projectGlobals.common, options, {
 				// The `_snippetsData` collection is used in `src/tasks/build-snippets.js` in order to build snippets.
-				// Required data are being added in hexo `after_post_render` filter: `scripts/filter/after-post-render/snippets.js`.
+				// Required data are being added in hexo `after_post_render` filter: `scripts/filter/after-post-render/snippets.cjs`.
 				/** @type {Map.<String, Set.<Snippet>>} */
 				_snippetsData: new Map(),
 
 				// The `_copiedFiles` collection is being built in `src/tasks/copy-project-docs.js` in order to find the source
-				// paths of copied files while processing snippets (see: `scripts/filter/after-post-render/snippets.js`).
+				// paths of copied files while processing snippets (see: `scripts/filter/after-post-render/snippets.cjs`).
 				/** @type {Map.<String, Map.<String, String>>} */
 				_copiedFiles: new Map(),
 
 				// The `_disabledFilters` collection contains names of filters that won't be executed.
 				// Unfortunately, the mechanism is not merged into Hexo core, so when writing a filter, you need to verify
-				// manually whether it should be executed. An example usage you can find in the `scripts/utils/parselinks.js` file.
+				// manually whether it should be executed. An example usage you can find in the `scripts/utils/parselinks.cjs` file.
 				/** @type {Set.<String>} */
 				_disabledFilters: new Set()
 			} );
@@ -237,4 +236,4 @@ class HexoManager {
 	}
 }
 
-module.exports = new HexoManager();
+export const hexoManager = new HexoManager();