umberto 9.3.0 → 10.0.0

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

@@ -3,12 +3,70 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+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';
 
-const upath = require( 'upath' );
-const getPageGroupHelper = require( '../helper/get-page-group' );
-const getDocSearchConfig = require( '../../helpers/get-docsearch-config' );
-const umbertoVersion = require( '../../../package.json' ).version;
+/**
+ * Resolves the API package name from a docs path.
+ *
+ * @param {Object} params
+ * @param {String} params.path
+ * @param {String} params.basePath
+ * @param {String|null} params.apiSlug
+ * @returns {String|null}
+ */
+function getApiPackageFromPath( { path, basePath, apiSlug } ) {
+	if ( !apiSlug ) {
+		return null;
+	}
+
+	const apiBasePath = upath.join( basePath, apiSlug );
+	const normalizedPath = upath.normalize( path );
+
+	if ( normalizedPath !== apiBasePath && !normalizedPath.startsWith( `${ apiBasePath }/` ) ) {
+		return null;
+	}
+
+	const firstSegment = normalizedPath
+		.slice( apiBasePath.length )
+		.replace( /^\/+/, '' )
+		.split( '/' )[ 0 ];
+
+	if ( !firstSegment || firstSegment === 'index.html' ) {
+		return null;
+	}
+
+	const packageName = firstSegment.replace( /\.html$/, '' );
+
+	return packageName === 'index' ? null : packageName;
+}
+
+/**
+ * Chooses the API tree HTML based on current page context.
+ *
+ * @param {Object} params
+ * @param {String} params.path
+ * @param {String} params.basePath
+ * @param {String|null} params.apiSlug
+ * @param {String} params.navTree
+ * @param {Object} params.navTreeByPackage
+ * @returns {String}
+ */
+function getApiTreeHtml( { path, basePath, apiSlug, navTree, navTreeByPackage } ) {
+	if ( !navTreeByPackage || Object.keys( navTreeByPackage ).length === 0 ) {
+		return navTree;
+	}
+
+	const apiPackage = getApiPackageFromPath( { path, basePath, apiSlug } );
+
+	if ( apiPackage && navTreeByPackage[ apiPackage ] ) {
+		return navTreeByPackage[ apiPackage ];
+	}
+
+	return navTree;
+}
 
 /**
  * Adds various project data as hexo locals available in templates.
@@ -27,11 +85,12 @@ const umbertoVersion = require( '../../../package.json' ).version;
  * @param {Array} extraStylePaths Paths to extra external css.
  * @param {Array} extraScriptsPaths Paths to extra external js.
  * @param {Boolean} disableSearch Extra flag for disabling docsearch if needed.
+ * @param {Boolean} shouldInjectNoIndexMeta Whether the "do not index" header for bots should be included.
  * @param {Array} quickNavigationProjects Projects to display in the quick navigation dropdown.
  * @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,
@@ -46,6 +105,7 @@ module.exports = ( ctx, {
 	extraStylePaths,
 	extraScriptsPaths,
 	disableSearch,
+	shouldInjectNoIndexMeta,
 	og,
 	quickNavigationProjects,
 	navigationShowEmptyCategories
@@ -63,10 +123,18 @@ module.exports = ( ctx, {
 				return g;
 			} );
 
+			const apiTree = getApiTreeHtml( {
+				path: locals.path,
+				basePath,
+				apiSlug: groupsModified.find( g => g.id === 'api-reference' )?.slug ?? null,
+				navTree: ctx.projectGlobals[ projectSlug ].config.navTree,
+				navTreeByPackage: ctx.projectGlobals[ projectSlug ].config.navTreeByPackage
+			} );
+
 			locals.projectLocals = {
 				groups: groupsModified,
 				getPageGroup: getPageGroupHelper( groupsModified ),
-				apiTree: ctx.projectGlobals[ projectSlug ].config.navTree,
+				apiTree,
 				sdkNavTree: ctx.projectGlobals[ projectSlug ].config.sdkNavTree,
 				latestBasePath: upath.join( projectSlug, 'latest' ),
 				extraStylePaths,
@@ -85,7 +153,10 @@ module.exports = ( ctx, {
 			};
 		}
 
-		// locals same for all projects
+		// ⚠️ WARNING ⚠️
+		// Following locals are the same for all projects. Each project overwrites previous ones.
+		// For unique values, use`projectLocals` or `projectsData`.
+
 		if ( !locals.projectsData ) {
 			locals.projectsData = [];
 		}
@@ -94,6 +165,7 @@ module.exports = ( ctx, {
 		locals.projectsData.push( {
 			name: projectName,
 			slug: projectSlug,
+			shouldInjectNoIndexMeta,
 			BASE_PATH: upath.join( projectSlug, config.version ),
 			latestBasePath: upath.join( projectSlug, 'latest' ),
 			startPage: config.startPage ? '/' + config.startPage : '/index.html'

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();

package/src/index.js

@@ -3,23 +3,22 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { styleText } = require( 'node:util' );
-const path = require( 'node:path' );
-const compileSass = require( './tasks/compile-sass' );
-const runWebpack = require( './tasks/run-webpack' );
-const copyAssets = require( './tasks/copy-assets' );
-const getMainConfig = require( './tasks/get-main-config' );
-const createSymLinks = require( './tasks/create-sym-links' );
-const buildDocumentation = require( './tasks/build-documentation' );
-const getProjectConfig = require( './tasks/get-project-config' );
-const watcher = require( './tasks/watcher' );
-const validateHtml = require( './tasks/validate-html-w3c' );
-const { version } = require( '../package.json' );
-const logWithTime = require( './helpers/log-with-time' );
-
-module.exports = {
+import { styleText } from 'node:util';
+import upath from 'upath';
+import { compileSass } from './tasks/compile-sass.js';
+import { runWebpack } from './tasks/run-webpack.js';
+import { copyAssets } from './tasks/copy-assets.js';
+import { getMainConfig } from './tasks/get-main-config.js';
+import { createSymLinks } from './tasks/create-sym-links.js';
+import { buildDocumentation } from './tasks/build-documentation.js';
+import { getProjectConfig } from './tasks/get-project-config.js';
+import { watchMd as watcher } from './tasks/watcher.js';
+import { logWithTime } from './helpers/log-with-time.js';
+import { umbertoVersion as version } from './helpers/umberto-version.js';
+
+const __dirname = import.meta.dirname;
+
+export const umberto = {
 	/**
 	 * Builds documentation for a single project.
 	 * Intended to use within project's task runner or along other build scripts.
@@ -70,17 +69,13 @@ module.exports = {
  */
 async function buildAndWatch( options ) {
 	const logTime = logWithTime( 'Building documentation' );
-	const outputDir = path.join( process.cwd(), 'build', 'docs' );
+	const outputDir = upath.join( process.cwd(), 'build', 'docs' );
 	const hexoManager = await buildDocumentation( options );
 
 	if ( !options.skipThemes ) {
 		await buildThemes( outputDir, options );
 	}
 
-	if ( options.validateW3C ) {
-		await validateHtml( outputDir, options );
-	}
-
 	if ( options.createSymLinks !== false ) {
 		const rootPath = process.cwd();
 
@@ -101,15 +96,15 @@ async function buildAndWatch( options ) {
 }
 
 async function buildThemes( outputDir, options ) {
-	const themesDir = path.join( __dirname, '../themes/umberto' );
-	const sourceDir = path.join( themesDir, 'src' );
-	const outputAssetsPath = path.join( outputDir, 'assets', version );
+	const themesDir = upath.join( __dirname, '../themes/umberto' );
+	const sourceDir = upath.join( themesDir, 'src' );
+	const outputAssetsPath = upath.join( outputDir, 'assets', version );
 	const layoutThemes = [ 'umberto', 'gloria' ];
 
 	for ( const theme of layoutThemes ) {
 		await runWebpack(
-			path.join( sourceDir, theme, 'js/app.js' ),
-			path.join( outputAssetsPath, theme, 'scripts' ),
+			upath.join( sourceDir, theme, 'js/app.js' ),
+			upath.join( outputAssetsPath, theme, 'scripts' ),
 			{
 				minify: !options.dev,
 				umbertoDir: themesDir,
@@ -118,17 +113,19 @@ async function buildThemes( outputDir, options ) {
 		);
 
 		await copyAssets(
-			path.join( themesDir, 'source', theme ),
-			path.join( outputAssetsPath, theme )
+			upath.join( themesDir, 'source', theme ),
+			upath.join( outputAssetsPath, theme )
 		);
 
 		await compileSass(
-			path.join( sourceDir, theme, 'css/styles.scss' ),
-			path.join( outputAssetsPath, theme, 'css/styles.css' )
+			upath.join( sourceDir, theme, 'css/styles.scss' ),
+			upath.join( outputAssetsPath, theme, 'css/styles.css' )
 		);
 	}
 }
 
+export default umberto;
+
 /**
  * @typedef {Object} Options
  * @property {boolean} [skipApi=false] Skips rendering API docs.
@@ -139,5 +136,4 @@ async function buildThemes( outputDir, options ) {
  * @property {boolean} [verbose=false] Adds more information to console during documentation building.
  * @property {boolean} [createSymLinks=true] Add symbolic links with 'latest' to output folder.
  * @property {boolean} [watch=false] Run Umberto with watch mode, which track changes in dm files and rebuild docs with it.
- * @property {boolean} [validateW3C=false] Use vnu java validator to check every single output page for html syntax errors.
  */

package/src/sdk-builder/get-sdk-sources.js

@@ -3,26 +3,24 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const fs = require( 'node:fs' );
-const upath = require( 'upath' );
-const { globSync } = require( 'glob' );
-const { parseDocument } = require( 'htmlparser2' );
-const { cloneNode, Text } = require( 'domhandler' );
-const { default: render } = require( 'dom-serializer' );
-const { selectAll, selectOne } = require( 'css-select' );
-const {
+import fs from 'node:fs';
+import upath from 'upath';
+import { globSync } from 'glob';
+import { parseDocument } from 'htmlparser2';
+import { cloneNode, Text } from 'domhandler';
+import render from 'dom-serializer';
+import { selectAll, selectOne } from 'css-select';
+import {
 	getAttributeValue,
 	hasAttrib,
 	textContent,
 	getName
-} = require( 'domutils' );
-const decodeHtmlEntities = require( '../../scripts/utils/decode-html-entities' );
+} from 'domutils';
+import decodeHtmlEntities from '../../scripts/utils/decode-html-entities.cjs';
 
 const SDK_SELECTOR = 'meta[name="sdk-samples"]';
 
-module.exports = sourcePath => {
+export const getSdkSources = sourcePath => {
 	const files = [];
 	const filePaths = globSync( upath.join( sourcePath, '*.html' ) ).map( path => upath.normalize( path ) );
 

package/src/sdk-builder/sdk-builder.js

@@ -3,17 +3,17 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+import { HtmlFile } from '../api-builder/classes/html-file.js';
+import upath from 'upath';
+import { URL, resolve as urlResolve } from 'node:url';
+import jsBeautify from 'js-beautify';
+import { macroReplacer } from '../tasks/macro-replacer.js';
+import { getDocsearchConfig as getDocSearchConfig } from '../helpers/get-docsearch-config.js';
+import { getIssueUrl, getContributeUrl } from '../helpers/github-url.js';
 
-const HtmlFile = require( '../api-builder/classes/html-file' );
-const upath = require( 'upath' );
-const { URL, resolve: urlResolve } = require( 'node:url' );
-const beautifyHtml = require( 'js-beautify' ).html;
-const macroReplacer = require( '../tasks/macro-replacer' );
-const getDocSearchConfig = require( '../helpers/get-docsearch-config' );
-const githubUrlUtils = require( '../helpers/github-url' );
+const { html: beautifyHtml } = jsBeautify;
 
-module.exports = class SdkBuilder {
+export class SdkBuilder {
 	constructor( {
 		sdkCollection,
 		template,
@@ -144,8 +144,8 @@ module.exports = class SdkBuilder {
 				presetVersion: sdkItem.presetVersion,
 				ckeditorVersion: this.projectConfig.version,
 				sdkSamples,
-				issuesUrl: githubUrlUtils.getIssueUrl( this.projectConfig ),
-				contributeUrl: githubUrlUtils.getContributeUrl( this.projectConfig, sdkGroup.sourceDir, sdkItem.name ),
+				issuesUrl: getIssueUrl( this.projectConfig ),
+				contributeUrl: getContributeUrl( this.projectConfig, sdkGroup.sourceDir, sdkItem.name ),
 				order: sdkItem && sdkItem.meta ? sdkItem.meta.order : 0,
 				canonicalUrlBeginning: this.canonicalUrlBeginning
 			};

package/src/tasks/build-api-docs.js

@@ -3,14 +3,12 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const upath = require( 'upath' );
-const readDocSources = require( './read-doc-sources' );
-const DataProvider = require( '../data-converter/data-provider' );
-const ApiBuilder = require( '../api-builder/api-builder' );
-const TemplateCollection = require( '../template/template-collection' );
-const logWithTime = require( '../helpers/log-with-time' );
+import upath from 'upath';
+import { readDocSources } from './read-doc-sources.js';
+import { DataProvider } from '../data-converter/data-provider.js';
+import { ApiBuilder } from '../api-builder/api-builder.js';
+import { TemplateCollection } from '../template/template-collection.js';
+import { logWithTime } from '../helpers/log-with-time.js';
 
 /**
  * Builds API docs.
@@ -21,7 +19,7 @@ const logWithTime = require( '../helpers/log-with-time' );
  * @param config
  * @returns {Promise<ApiBuilder>}
  */
-module.exports = async config => {
+export const buildApiDocs = async config => {
 	const {
 		src,
 		projectDst, // e.g.: ckeditor5/latest/api