umberto 3.2.1 → 4.0.0

package/CHANGELOG.md

@@ -1,6 +1,37 @@
 Changelog
 =========
 
+## [4.0.0](https://github.com/cksource/umberto/compare/v3.2.2...v4.0.0) (2023-10-10)
+
+### BREAKING CHANGES
+
+* Upgraded the minimal versions of Node.js to `18.0.0` due to the end of LTS.
+
+### Bug fixes
+
+* Added support for perm-link feature on API pages. Closes [#1167](https://github.com/cksource/umberto/issues/1167). ([commit](https://github.com/cksource/umberto/commit/20d167082e126541d3f2867ebebcf57b6c3173f8))
+* Added the `[title]` attribute to the Table of Content and the navigation menu items. Closes [#1175](https://github.com/cksource/umberto/issues/1175). ([commit](https://github.com/cksource/umberto/commit/8f3c15f96864a4e8320d26fb2b0c00746529e06b))
+* Fixed the "See source" button to be clickable when an item does not have a description. Closes [#1172](https://github.com/cksource/umberto/issues/1172). ([commit](https://github.com/cksource/umberto/commit/05b4e3c6893a8d4fdafd5e48c0293a1a50670a35))
+
+### Other changes
+
+* Replaced the hyphen-minus  (`-`) separator with a vertical pipe (`|`) in the generated title of pages. ([commit](https://github.com/cksource/umberto/commit/8bf6a3afb7337d7d816c3a5206eb3088bc1edf29))
+* Updated the required version of Node.js to 18. See [ckeditor/ckeditor5#14924](https://github.com/ckeditor/ckeditor5/issues/14924). ([commit](https://github.com/cksource/umberto/commit/c7ee14ee127ae5b497569a687e731c40fa6378ef))
+
+
+## [3.2.2](https://github.com/cksource/umberto/compare/v3.2.1...v3.2.2) (2023-08-28)
+
+### Bug fixes
+
+* Fixed jumping layout in the secondary (table of content) navigation in a case when a text is just barely fitting a single line. When it gets highlighted and the font geometry changes, and it gets to two lines. Closes [cksource/umberto#1152](https://github.com/cksource/umberto/issues/1152). ([commit](https://github.com/cksource/umberto/commit/102674435ea8f70c321d7c029bf984ddc16f7855))
+* HTML tags will no longer render in ToC. Closes [#1157](https://github.com/cksource/umberto/issues/1157). ([commit](https://github.com/cksource/umberto/commit/cc44e61f496bef25f34d8e2d41eca8e849a54924))
+* Skip search results from API on the root page in documentation. Closes [#1029](https://github.com/cksource/umberto/issues/1029). ([commit](https://github.com/cksource/umberto/commit/b4f9250a43ff887da6da7f042434aa1542582ea7))
+
+### Other changes
+
+* The Google Analytics `<script>` tag produces output compatible with the latest version (v4). Closes [#1166](https://github.com/cksource/umberto/issues/1166). ([commit](https://github.com/cksource/umberto/commit/0cefecde3ccc12f171580dded361895bfb0b12cd))
+
+
 ## [3.2.1](https://github.com/cksource/umberto/compare/v3.2.0...v3.2.1) (2023-06-21)
 
 Internal changes only (updated dependencies, documentation, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "3.2.1",
+  "version": "4.0.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -57,8 +57,7 @@
     "webpack": "^5.74.0"
   },
   "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=5.7.1"
+    "node": ">=18.0.0"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "MIT",

package/scripts/helper/u-toc.js

@@ -33,9 +33,13 @@ hexo.extend.helper.register( 'uToc', ( data, options = {} ) => {
 
 	headings.each( function() {
 		const hLevel = Number( this.name[ 1 ] );
-		const text = $r( this ).find( '.headerlink' ).remove().end().text().trim();
 		const id = $r( this ).attr( 'id' );
-		const newItem = `<li><a href="#${ id }">${ text }</a></li>`;
+		const text = $r( this ).find( '.headerlink' ).remove().end().text().trim()
+			// Replace the chevrons with their HTML escape characters to avoid rendering HTML in ToC.
+			.replace( /</g, '&lt;' )
+			.replace( />/g, '&gt;' );
+
+		const newItem = `<li><a href="#${ id }" title="${ text }">${ text }</a></li>`;
 
 		if ( tocLastLevels[ hLevel ] ) {
 			// If there already is a parent node for current heading level, append the new toc item there.

package/src/helpers/get-docsearch-config.js

@@ -5,8 +5,14 @@
 
 'use strict';
 
-const { stringify } = require( 'javascript-stringify' );
 const { cloneDeep } = require( 'lodash' );
+const { stringify } = require( 'javascript-stringify' );
+const fs = require( 'fs' );
+const upath = require( 'upath' );
+
+const defaultScriptTemplate = fs.readFileSync( upath.join( __dirname, 'templates', 'scripts', 'default.js' ), 'utf-8' );
+const groupScriptTemplate = fs.readFileSync( upath.join( __dirname, 'templates', 'scripts', 'group.js' ), 'utf-8' );
+const rootScriptTemplate = fs.readFileSync( upath.join( __dirname, 'templates', 'scripts', 'root.js' ), 'utf-8' );
 
 module.exports = ( searchConfig, {
 	groups = [],
@@ -25,7 +31,7 @@ module.exports = ( searchConfig, {
 	const options = {
 		inputSelector: '#docsearch_input',
 		algoliaOptions: {
-			hitsPerPage: 10,
+			hitsPerPage: 250,
 			attributesToRetrieve: '*'
 		}
 	};
@@ -35,7 +41,7 @@ module.exports = ( searchConfig, {
 		dConfig,
 		options,
 		{
-			isEnabled: dConfig.apiKey && dConfig.indexName,
+			isEnabled: Boolean( dConfig.apiKey && dConfig.indexName ),
 			css: 'https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css',
 			js: 'https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js'
 		}
@@ -58,7 +64,6 @@ module.exports = ( searchConfig, {
 
 	if ( transformDataFunctions ) {
 		for ( const tag of Object.keys( transformDataFunctions ) ) {
-			innerConfig.algoliaOptions.hitsPerPage = 250;
 			const innerConfigStr = stringify( innerConfig ).replace( /^{|}$/g, '' );
 
 			docSearchConfig.scripts[ tag ] = [
@@ -88,144 +93,35 @@ module.exports = ( searchConfig, {
 };
 
 function getTransformDataFns( groups, slug ) {
-	if ( !Array.isArray( groups ) || groups.length === 0 ) {
-		return null;
-	}
+	const functions = {
+		rootScript: fillTemplate( rootScriptTemplate.toString() )
+	};
 
-	const functions = {};
-	const tags = `[ ${ groups.map( g => `'${ g.slug }'` ).join( ', ' ) } ]`;
-
-	for ( const g of groups ) {
-		functions[ g.slug ] = [
-			'function( hits ) {',
-
-			'var sortingFn = function( a, b ) {',
-			'a.custom_ranking = a.custom_ranking || 0;',
-			'b.custom_ranking = b.custom_ranking || 0;',
-
-			'if ( a.custom_ranking === b.custom_ranking ) return a.index - b.index;',
-			'if ( a.custom_ranking > b.custom_ranking ) return -1;',
-			'if ( a.custom_ranking < b.custom_ranking ) return 1;',
-			'};',
-
-			'var result = [];',
-			`var tags = ${ tags };`,
-
-			'var hitsGrouped = { api: [] };',
-
-			`hitsGrouped[ '${ g.slug }' ] = hits`,
-			'.filter( function( h ) {',
-			`return h.tags.includes( '${ slug }' ) && h.tags.includes( '${ g.slug }' );`,
-			'} )',
-			'.slice( 0, 7 )',
-			'.map( function( item, idx ) {',
-			'item.index = idx;',
-			'return item;',
-			'} )',
-			'.sort( sortingFn );',
-
-			'tags.forEach( function( tag ) {',
-			`if ( tag !== '${ g.slug }' ) {`,
-			'hitsGrouped[ tag ] = hits',
-			'.filter( function( h ) {',
-			`return h.tags.includes( '${ slug }' ) && h.tags.includes( tag );`,
-			'} )',
-			'.slice( 0, 10 )',
-			'.map( function( item, idx ) {',
-			'item.index = idx;',
-			'return item;',
-			'} )',
-			'.sort( sortingFn )',
-			'.slice( 0, 3 );',
-			'}',
-			'} );',
-
-			'var apiSearchHits = [];',
-
-			'if ( window.apiSearch ) apiSearchHits = window.apiSearch();',
-
-			'hitsGrouped.api = hitsGrouped.api.filter( function( h ) {',
-			'var isDuplicated = false;',
-
-			'for ( var i = 0; i < apiSearchHits.length; i++ ) {',
-			'if ( h.url.includes( apiSearchHits[ i ].urlShort ) ) {',
-			'isDuplicated = true;',
-			'break;',
-			'}',
-			'}',
-
-			'return !isDuplicated;',
-			'} );',
-
-			'hitsGrouped.api = ( apiSearchHits || [] ).concat( hitsGrouped.api );',
-
-			`result = result.concat( hitsGrouped[ '${ g.slug }' ] );`,
-
-			'tags.forEach( function( tag ) {',
-			`if ( tag !== '${ g.slug }' ) result = result.concat( hitsGrouped[ tag ].slice( 0, 4 ) );`,
-			'} );',
-
-			'return result;',
-			'}'
-		].join( '' );
+	if ( !Array.isArray( groups ) || groups.length === 0 ) {
+		return functions;
 	}
 
-	functions.defaultScript = [
-		'function( hits ) {',
-		'var sortingFn = function( a, b ) {',
-		'a.custom_ranking = a.custom_ranking || 0;',
-		'b.custom_ranking = b.custom_ranking || 0;',
-
-		'if ( a.custom_ranking === b.custom_ranking ) return a.index - b.index;',
-		'if ( a.custom_ranking > b.custom_ranking ) return -1;',
-		'if ( a.custom_ranking < b.custom_ranking ) return 1;',
-		'};',
+	const tags = `${ groups.map( group => `${ group.slug }` ).join( '\', \'' ) }`;
 
-		'var result = [];',
-		`var tags = ${ tags };`,
+	for ( const group of groups ) {
+		const groupSlug = group.slug;
 
-		'var hitsGrouped = { api: [] };',
-
-		'tags.forEach( function( tag ) {',
-		'hitsGrouped[ tag ] = hits',
-		'.filter( function( h ) {',
-		`return h.tags.includes( '${ slug }' ) && h.tags.includes( tag );`,
-		'} )',
-		'.slice( 0, 10 )',
-		'.map( function( item, idx ) {',
-		'item.index = idx;',
-		'return item;',
-		'} )',
-		'.sort( sortingFn )',
-		'.slice( 0, 3 );',
-		'} );',
-
-		'var apiSearchHits = [];',
-
-		'if ( window.apiSearch ) apiSearchHits = window.apiSearch();',
-
-		'hitsGrouped.api = hitsGrouped.api.filter( function( h ) {',
-		'var isDuplicated = false;',
+		functions[ groupSlug ] = fillTemplate( groupScriptTemplate.toString(), { tags, slug, groupSlug } );
+	}
 
-		'for ( var i = 0; i < apiSearchHits.length; i++ ) {',
-		'if ( h.url.includes( apiSearchHits[ i ].urlShort ) ) {',
-		'isDuplicated = true;',
-		'break;',
-		'}',
-		'}',
+	functions.defaultScript = fillTemplate( defaultScriptTemplate.toString(), { tags, slug } );
 
-		'return !isDuplicated;',
-		'} );',
+	return functions;
+}
 
-		'hitsGrouped.api = ( apiSearchHits || [] ).concat( hitsGrouped.api );',
+function fillTemplate( template, data ) {
+	let updatedTemplate = template.replace( /^function [\S]+\( hits \)/, 'function( hits )' );
 
-		'tags.forEach( function( tag ) {',
-		'result = result.concat( hitsGrouped[ tag ].slice( 0, 4 ) );',
-		'} );',
+	for ( const key in data ) {
+		const pattern = new RegExp( `{{{ ${ key } }}}`, 'g' );
 
-		'return result;',
-		'}'
-	].join( '' );
+		updatedTemplate = updatedTemplate.replace( pattern, data[ key ] );
+	}
 
-	return functions;
+	return updatedTemplate.replace( /\n\s*/g, '' );
 }

package/src/helpers/templates/scripts/default.js

@@ -0,0 +1,54 @@
+function defaultScript( hits ) {
+	var sortingFn = function( a, b ) {
+		a.custom_ranking = a.custom_ranking || 0;
+		b.custom_ranking = b.custom_ranking || 0;
+
+		if ( a.custom_ranking === b.custom_ranking ) return a.index - b.index;
+		if ( a.custom_ranking > b.custom_ranking ) return -1;
+		if ( a.custom_ranking < b.custom_ranking ) return 1;
+	};
+
+	var result = [];
+	var tags = [ '{{{ tags }}}' ];
+
+	var hitsGrouped = { api: [] };
+
+	tags.forEach( function( tag ) {
+		hitsGrouped[ tag ] = hits
+			.filter( function( h ) {
+				return h.tags.includes( '{{{ slug }}}' ) && h.tags.includes( tag );
+			} )
+			.slice( 0, 10 )
+			.map( function( item, idx ) {
+				item.index = idx;
+				return item;
+			} )
+			.sort( sortingFn )
+			.slice( 0, 3 );
+	} );
+
+	var apiSearchHits = [];
+
+	if ( window.apiSearch ) apiSearchHits = window.apiSearch();
+
+	hitsGrouped.api = hitsGrouped.api.filter( function( h ) {
+		var isDuplicated = false;
+
+		for ( var i = 0; i < apiSearchHits.length; i++ ) {
+			if ( h.url.includes( apiSearchHits[ i ].urlShort ) ) {
+				isDuplicated = true;
+				break;
+			}
+		}
+
+		return !isDuplicated;
+	} );
+
+	hitsGrouped.api = ( apiSearchHits || [] ).concat( hitsGrouped.api );
+
+	tags.forEach( function( tag ) {
+		result = result.concat( hitsGrouped[ tag ].slice( 0, 4 ) );
+	} );
+
+	return result;
+}

package/src/helpers/templates/scripts/group.js

@@ -0,0 +1,69 @@
+function groupScript( hits ) {
+	var sortingFn = function( a, b ) {
+		a.custom_ranking = a.custom_ranking || 0;
+		b.custom_ranking = b.custom_ranking || 0;
+
+		if ( a.custom_ranking === b.custom_ranking ) return a.index - b.index;
+		if ( a.custom_ranking > b.custom_ranking ) return -1;
+		if ( a.custom_ranking < b.custom_ranking ) return 1;
+	};
+
+	var result = [];
+	var tags = [ '{{{ tags }}}' ];
+
+	var hitsGrouped = { api: [] };
+
+	hitsGrouped[ '{{{ groupSlug }}}' ] = hits
+		.filter( function( h ) {
+			return h.tags.includes( '{{{ slug }}}' ) && h.tags.includes( '{{{ groupSlug }}}' );
+		} )
+		.slice( 0, 7 )
+		.map( function( item, idx ) {
+			item.index = idx;
+			return item;
+		} )
+		.sort( sortingFn );
+
+	tags.forEach( function( tag ) {
+		if ( tag !== '{{{ groupSlug }}}' ) {
+			hitsGrouped[ tag ] = hits
+				.filter( function( h ) {
+					return h.tags.includes( '{{{ slug }}}' ) && h.tags.includes( tag );
+				} )
+				.slice( 0, 10 )
+				.map( function( item, idx ) {
+					item.index = idx;
+					return item;
+				} )
+				.sort( sortingFn )
+				.slice( 0, 3 );
+		}
+	} );
+
+	var apiSearchHits = [];
+
+	if ( window.apiSearch ) apiSearchHits = window.apiSearch();
+
+	hitsGrouped.api = hitsGrouped.api.filter( function( h ) {
+		var isDuplicated = false;
+
+		for ( var i = 0; i < apiSearchHits.length; i++ ) {
+			if ( h.url.includes( apiSearchHits[ i ].urlShort ) ) {
+				isDuplicated = true;
+				break;
+			}
+		}
+
+		return !isDuplicated;
+	} );
+
+	hitsGrouped.api = ( apiSearchHits || [] ).concat( hitsGrouped.api );
+
+	result = result.concat( hitsGrouped[ '{{{ groupSlug }}}' ] );
+
+	tags.forEach( function( tag ) {
+		if ( tag !== '{{{ groupSlug }}}' ) result = result.concat( hitsGrouped[ tag ].slice( 0, 4 ) );
+	} );
+
+	return result;
+}

package/src/helpers/templates/scripts/root.js

@@ -0,0 +1,21 @@
+function rootScript( hits ) {
+	var sortingFn = function( a, b ) {
+		a.custom_ranking = a.custom_ranking || 0;
+		b.custom_ranking = b.custom_ranking || 0;
+
+		if ( a.custom_ranking === b.custom_ranking ) return a.index - b.index;
+		if ( a.custom_ranking > b.custom_ranking ) return -1;
+		if ( a.custom_ranking < b.custom_ranking ) return 1;
+	};
+
+	return hits
+		.filter( function( h ) {
+			return !h.tags.includes( 'api' );
+		} )
+		.slice( 0, 10 )
+		.map( function( item, idx ) {
+			item.index = idx;
+			return item;
+		} )
+		.sort( sortingFn );
+}

package/themes/umberto/layout/_api-docs/api-base.pug

@@ -35,3 +35,8 @@ block content
 
 block navtree
     != navTree
+
+block projectVersion
+    if projectLocals
+        meta( name= 'project-version' content= projectLocals.projectVersion )
+        meta( name= 'project-slug' content= projectLocals.projectSlug )

package/themes/umberto/layout/_mixin/nav-tree-item.pug

@@ -2,7 +2,7 @@ mixin navTreeItem( data )
 	- const _class = page.path === data.path ? 'tree__item__wrapper tree__item__wrapper--active' : 'tree__item__wrapper';
 	- const menuTitle = data[ 'menu-title' ] || uSplitToTitleAndContent( data.content ).title || data.title;
 	li
-		a( href=relative_url( page.path, data.path ) )
+		a( href=relative_url( page.path, data.path ) title=menuTitle )
 			div( class=_class )
 				span( class="tree__item--guide tree__item__text" ) #{ menuTitle }
 				- if( data.shouldDisplayNewIndicator )

package/themes/umberto/layout/_partial/docsearch.pug

@@ -13,7 +13,9 @@ if ( docSearchConfig && docSearchConfig.isEnabled && !disableSearch && (!project
 
     script( src=config.js )
 
-    if ( !page.groupSlug || !config.scripts[ page.groupSlug ] )
+    if ( page.path === 'index.html' )
+        != config.scripts.rootScript
+    else if ( !page.groupSlug || !config.scripts[ page.groupSlug ] )
         != config.scripts.defaultScript
     else
         != config.scripts[ page.groupSlug ]

package/themes/umberto/layout/_partial/google-analytics.pug

@@ -1,25 +1,19 @@
 if googleanalytics && !googletagmanager
 	script.
 		if ( !{ JSON.stringify( googleanalytics.domains ) }.indexOf( location.hostname ) !== -1 ) {
-			function pageView() {
-				ga( 'send', 'pageview', location.pathname + location.search + location.hash );
-			}
-
-			(function( i, s, o, g, r, a, m ) {
-				i[ 'GoogleAnalyticsObject' ] = r;
-				i[ r ] = i[ r ] || function() {
-						(i[ r ].q = i[ r ].q || []).push( arguments )
-					}, i[ r ].l = 1 * new Date();
-				a = s.createElement( o ),
-					m = s.getElementsByTagName( o )[ 0 ];
+			( function ( w, d, e, u, a, b ) {
+				a = d.createElement( e );
+				b = d.getElementsByTagName( e )[ 0 ];
 				a.async = 1;
-				a.src = g;
-				m.parentNode.insertBefore( a, m )
-			})( window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga' );
+				a.src = u;
+				b.parentNode.insertBefore( a, b )
+			} )( window, document, 'script', 'https://www.googletagmanager.com/gtag/js?id=!{ googleanalytics.config.trackingId }' );
+			window.dataLayer = window.dataLayer || [];
 
-			ga( 'create', !{ JSON.stringify( googleanalytics.config ) } );
-
-			pageView();
+			function gtag() {
+				dataLayer.push( arguments );
+			}
 
-			window.addEventListener( 'hashchange', pageView );
+			gtag( 'js', new Date() );
+			gtag( 'config', '!{ googleanalytics.config.trackingId }' );
 		}

package/themes/umberto/layout/_partial/head.pug

@@ -2,7 +2,7 @@ meta( charset='utf-8' )
 meta( name='viewport' content='width=device-width, initial-scale=1' )
 
 - const titleSuffix = page.groupId === 'api-reference' ? page.projectfullname + ' API docs' : page.projectfullname + ' Documentation';
-- const title = page[ 'meta-title' ] ? page[ 'meta-title' ] : page[ 'meta-title-short' ] ? page[ 'meta-title-short' ] + ' - ' + titleSuffix : page.title + ' - ' + titleSuffix;
+- const title = page[ 'meta-title' ] ? page[ 'meta-title' ] : page[ 'meta-title-short' ] ? page[ 'meta-title-short' ] + ' | ' + titleSuffix : page.title + ' | ' + titleSuffix;
 title= title
 
 //- Used for meta tag and for og:*

package/themes/umberto/src/css/_api-content.scss

@@ -18,6 +18,9 @@
 				// To keep vertical align with paragraph.
 				top: 0.2em;
 
+				// To keep "See source" link clickable.
+				z-index: 1;
+
 				// If "See source" exists, we need to add spacing to first paragraph to prevent overlapping text.
 				+ .main-description p:first-child{
 					padding-right: 100px;

package/themes/umberto/src/css/_secondary-navigation.scss

@@ -68,7 +68,7 @@ nav.secondary-navigation {
 
 		&.secondary-navigation__current-position {
 			color: u-color( 'link' );
-			font-weight: bold;
+			-webkit-text-stroke-width: thin;
 
 			&::before {
 				opacity: 1;