umberto 2.1.5 → 2.1.7

package/hexo-config.json

@@ -7,6 +7,7 @@
 	"public_dir": "build/docs",
 	"theme": "umberto",
 	"external_link": {
+		"enable": true,
 		"exclude": [
 			"ckeditor.com"
 		]
@@ -24,6 +25,7 @@
 	  	"highlight": false,
 	  	"html": true,
 	  	"breaks": true,
+		"linkify": false,
 		"plugins": [
 			{
 				"plugin": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -13,58 +13,58 @@
     "hexo-shim.js"
   ],
   "dependencies": {
-    "@babel/core": "^7.10.3",
-    "@babel/polyfill": "^7.10.1",
-    "@babel/preset-env": "^7.10.3",
-    "@ckeditor/jsdoc-plugins": "^30.1.4",
-    "babel-loader": "^8.1.0",
+    "@babel/core": "^7.18.10",
+    "@babel/polyfill": "^7.12.1",
+    "@babel/preset-env": "^7.18.10",
+    "@ckeditor/jsdoc-plugins": "^30.3.5",
+    "babel-loader": "^8.2.5",
     "chalk": "^4.1.0",
-    "cheerio": "^0.22.0",
+    "cheerio": "^1.0.0-rc.12",
     "cpx": "^1.5.0",
-    "del": "^5.1.0",
+    "del": "^6.1.1",
     "element-closest": "^3.0.2",
     "escape-string-regexp": "^4.0.0",
-    "fs-extra": "^9.0.1",
-    "fuse.js": "^6.2.1",
-    "hexo": "^4.2.1",
+    "fs-extra": "^10.1.0",
+    "fuse.js": "^6.6.2",
+    "hexo": "^6.2.0",
     "hexo-generator-archive": "^1.0.0",
     "hexo-generator-category": "^1.0.0",
     "hexo-generator-index": "^1.0.0",
     "hexo-generator-tag": "^1.0.0",
     "hexo-render-pug": "^2.1.4",
-    "hexo-renderer-markdown-it-plus": "^1.0.4",
-    "javascript-stringify": "^2.0.1",
-    "jquery": "~3.5.1",
-    "js-beautify": "^1.11.0",
-    "lodash": "^4.17.15",
+    "hexo-renderer-markdown-it-plus": "^1.0.5",
+    "javascript-stringify": "^2.1.0",
+    "jquery": "~3.6.0",
+    "js-beautify": "^1.14.4",
+    "lodash": "^4.17.21",
     "markdown-it-expand-tabs": "^1.0.13",
     "markdown-it-toc-and-anchor": "^4.2.0",
-    "medium-zoom": "^1.0.5",
+    "medium-zoom": "^1.0.6",
+    "minimatch": "^5.1.0",
     "mkdirp": "^1.0.4",
-    "moment": "^2.27.0",
-    "minimatch": "^3.1.2",
-    "nyc": "15.1.0",
-    "pug": "^3.0.0",
-    "sass": "^1.43.4",
-    "sitemap": "^6.1.6",
-    "tippy.js": "^6.3.2",
+    "moment": "^2.29.4",
+    "nyc": "^15.1.0",
+    "pug": "^3.0.2",
+    "sass": "^1.54.0",
+    "sitemap": "^7.1.1",
+    "tippy.js": "^6.3.7",
     "tree-model": "^1.0.7",
-    "upath": "^2.0.0",
-    "vnu-jar": "^20.5.29",
-    "webpack": "^5.58.1"
+    "upath": "^2.0.1",
+    "vnu-jar": "^21.10.12",
+    "webpack": "^5.74.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-dev-env": "^30.1.4",
-    "browser-sync": "^2.26.7",
-    "chai": "^4.3.4",
-    "chokidar": "^3.4.0",
-    "eslint": "^7.3.0",
-    "eslint-config-ckeditor5": "^4.0.0",
-    "husky": "^4.2.5",
-    "lint-staged": "^10.2.11",
-    "mocha": "^8.3.2",
+    "@ckeditor/ckeditor5-dev-env": "^30.3.5",
+    "browser-sync": "^2.27.10",
+    "chai": "^4.3.6",
+    "chokidar": "^3.5.3",
+    "eslint": "^8.21.0",
+    "eslint-config-ckeditor5": "^4.0.1",
+    "husky": "^8.0.0",
+    "lint-staged": "^13.0.3",
+    "mocha": "^10.0.0",
     "mockery": "^2.1.0",
-    "sinon": "^10.0.0"
+    "sinon": "^14.0.0"
   },
   "engines": {
     "node": ">=14.0.0",
@@ -79,7 +79,8 @@
     "coverage": "nyc --reporter=lcov --reporter=text-summary --cache false npm run test",
     "changelog": "node ./scripts-dev/changelog.js",
     "release:bump-version": "node ./scripts-dev/bump-version.js",
-    "release:publish": "node ./scripts-dev/publish.js"
+    "release:publish": "node ./scripts-dev/publish.js",
+    "prepare": "husky install"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "MIT",
@@ -99,12 +100,7 @@
     "coverage/**",
     "packages/**"
   ],
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
   "hexo": {
-    "version": "4.2.1"
+    "version": "6.2.0"
   }
 }

package/scripts/filter/after-post-render/fix-code-samples.js

@@ -5,13 +5,13 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 
 /**
  * Fixes some codeblocks issues.
  */
 hexo.extend.filter.register( 'after_post_render', page => {
-	const $ = cheerio.load( page.content );
+	const $ = cheerio.load( page.content, null, false );
 
 	// This is an attempt to automatically discover code blocks of HTML and add 'html' class if needed.
 	// It is needed for triple backtick ``` codeblocks in markdown which contain HTML but don't use ```html notation.

package/scripts/filter/after-post-render/insert-error-codes.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 const upath = require( 'upath' );
 
 /**
@@ -23,7 +23,7 @@ hexo.extend.filter.register( 'after_post_render', page => {
 	}
 
 	const errorsHtml = hexo.projectGlobals[ page.projectName ].errorsHtml;
-	const $ = cheerio.load( errorsHtml );
+	const $ = cheerio.load( errorsHtml, null, false );
 
 	// Errors are used in guides so links must be converted to have proper paths. Converting links to API here.
 	$( 'a[href]' ).each( function() {

package/scripts/filter/after-post-render/validate-after-render.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 
 /**
  * Make sure each page has a title.
@@ -19,7 +19,7 @@ hexo.extend.filter.register( 'after_post_render', page => {
 		return;
 	}
 
-	const $ = cheerio.load( page.content );
+	const $ = cheerio.load( page.content, null, false );
 	const title = $( 'h1:not( .live-snippet h1 )' ).first();
 
 	if ( !title.length && !page.title ) {

package/scripts/helper/u-split-to-title-and-content.js

@@ -5,10 +5,10 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 
 hexo.extend.helper.register( 'uSplitToTitleAndContent', data => {
-	const $ = cheerio.load( data );
+	const $ = cheerio.load( data, null, false );
 	const title = $( 'h1:not( .live-snippet h1 )' ).first().remove();
 
 	return {

package/scripts/helper/u-toc.js

@@ -5,10 +5,10 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 
 hexo.extend.helper.register( 'uToc', ( data, options = {} ) => {
-	const $ = cheerio.load( data );
+	const $ = cheerio.load( data, null, false );
 
 	let usedHeadings = [ 'h2', 'h3', 'h4', 'h5', 'h6' ];
 
@@ -28,7 +28,7 @@ hexo.extend.helper.register( 'uToc', ( data, options = {} ) => {
 		return '';
 	}
 
-	const $r = cheerio.load( `<nav class=${ className }><h3>Table of contents</h3></nav>` ); // result object
+	const $r = cheerio.load( `<nav class=${ className }><h3>Table of contents</h3></nav>`, null, false ); // result object
 	const tocLastLevels = [ $r( 'nav' ), 0, 0, 0, 0, 0, 0 ];
 
 	headings.each( function() {

package/src/api-builder/api-builder.js

@@ -7,7 +7,7 @@
 
 const upath = require( 'upath' );
 const fs = require( 'fs-extra' );
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 const FileNameManager = require( './classes/file-name-manager' );
 const HtmlFile = require( './classes/html-file' );
 const DocDataFactory = require( './classes/doc-data-factory' );
@@ -397,7 +397,7 @@ module.exports = class ApiBuilder {
 					title = `${ capitalize( data.kind ) } ${ capitalize( split.name ) } (${ data.longname.replace( 'module:', '' ) })`;
 				}
 
-				const $ = data.description ? cheerio.load( data.description.content ) : cheerio.load( '' );
+				const $ = data.description ? cheerio.load( data.description.content, null, false ) : cheerio.load( '', null, false );
 				const html = $.root();
 				html.find( 'pre' ).remove();
 				const desc = html.text().trim().replace( /\n/g, ' ' ).replace( / +/g, ' ' );

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

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 const splitLongname = require( '../../helpers/split-longname' );
 const chalk = require( 'chalk' );
 const macroReplacer = require( '../../tasks/macro-replacer' );
@@ -52,7 +52,7 @@ module.exports = class DescriptionParser {
 				};
 			}
 
-			const $ = cheerio.load( str );
+			const $ = cheerio.load( str, null, false );
 			const excerpt = $( 'p' ).first().remove().html();
 			const content = $.html();
 
@@ -222,7 +222,7 @@ module.exports = class DescriptionParser {
 			return data;
 		}
 
-		const $ = cheerio.load( data );
+		const $ = cheerio.load( data, null, false );
 
 		$( ':header' ).replaceWith( ( i, item ) => {
 			const headerLevel = Number( item.name.slice( -1 ) );
@@ -244,7 +244,7 @@ module.exports = class DescriptionParser {
 			return str;
 		}
 
-		const $ = cheerio.load( str );
+		const $ = cheerio.load( str, null, false );
 
 		$( 'pre[class~="source"]' ).each( function() {
 			let code = $( this ).html();

package/src/api-builder/classes/doc-data-factory.js

@@ -91,9 +91,9 @@ module.exports = class DocDataFactory {
 		const functions = moduleMembersCollection.get( 'function' );
 		const members = moduleMembersCollection.get( 'member' );
 		const constants = moduleMembersCollection.get( 'constant' );
-		const functionsProcessed = this._getMembersWithExcerpt( functions, { parentDoclet: doclet } ) || [];
-		const membersProcessed = this._getMembersWithExcerpt( members, { parentDoclet: doclet } ) || [];
-		const constantsProcessed = this._getMembersWithExcerpt( constants, { parentDoclet: doclet } ) || [];
+		const functionsProcessed = this._getMembers( functions, { parentDoclet: doclet } ) || [];
+		const membersProcessed = this._getMembers( members, { parentDoclet: doclet } ) || [];
+		const constantsProcessed = this._getMembers( constants, { parentDoclet: doclet } ) || [];
 
 		return Object.assign( base, {
 			classes: classes.map( el => this.getClassShort( el, true ) ),
@@ -118,7 +118,6 @@ module.exports = class DocDataFactory {
 		const description = this._descriptionParser.parseDescription( doclet.description, {
 			doclet,
 			asMember,
-			withExcerpt: true,
 			buildInfo: this._options.buildInfo
 		} );
 
@@ -167,7 +166,7 @@ module.exports = class DocDataFactory {
 		const augmentsNested = doclet.augmentsNested ? doclet.augmentsNested : [];
 		augmentsNested.unshift( doclet.longname );
 		augmentsNested.reverse();
-		const properties = this._getMembersWithExcerpt( doclet.properties, { parentDoclet: doclet } ) || [];
+		const properties = this._getMembers( doclet.properties, { parentDoclet: doclet } ) || [];
 
 		/* eslint-disable max-len */
 		// For all "typedef" doclets - copy property name as its id. Thanks to that we will be able to make a directly link to specified property. See #796.
@@ -243,10 +242,10 @@ module.exports = class DocDataFactory {
 		const properties = classMembersCollection.get( 'member' );
 		const methods = classMembersCollection.get( 'function' );
 		const events = classMembersCollection.get( 'event' );
-		const configOptionsProcessed = this._getMembersWithExcerpt( configOptions, { parentDoclet: doclet } );
+		const configOptionsProcessed = this._getMembers( configOptions, { parentDoclet: doclet } );
 		// Sorting properties alphabetically and also public > protected > private.
 		const propertiesProcessed = sortPartsAlphabetically(
-			this._getMembersWithExcerpt( properties, { parentDoclet: doclet } ),
+			this._getMembers( properties, { parentDoclet: doclet } ),
 			[
 				{
 					key: 'access',
@@ -266,7 +265,7 @@ module.exports = class DocDataFactory {
 		const staticProperties = Array.isArray( propertiesProcessed ) ? propertiesProcessed.filter( p => p.scope === 'static' ) : [];
 		const instanceProperties = Array.isArray( propertiesProcessed ) ? propertiesProcessed.filter( p => p.scope !== 'static' ) : [];
 		const methodsProcessed = sortPartsAlphabetically(
-			this._getMembersWithExcerpt( methods, { parentDoclet: doclet } ),
+			this._getMembers( methods, { parentDoclet: doclet } ),
 			[
 				{
 					key: 'name',
@@ -301,7 +300,7 @@ module.exports = class DocDataFactory {
 			methods: methodsProcessed,
 			staticMethods,
 			instanceMethods,
-			events: this._getMembersWithExcerpt( events, {
+			events: this._getMembers( events, {
 				callback: item => {
 					item.name = item.name.replace( 'event:', '' );
 
@@ -324,7 +323,7 @@ module.exports = class DocDataFactory {
 	getErrors() {
 		const errors = this._dataCollection.get( 'error' ).getAll();
 
-		return this._getMembersWithExcerpt( errors );
+		return this._getMembers( errors );
 	}
 
 	/**

package/src/data-converter/converters/jsduck2umberto.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 const keyNameMap = {
 	tagname: {
 		name: 'kind',
@@ -161,7 +161,7 @@ function tagnameAdapter( item ) {
 
 function docAdapter( item ) {
 	const description = item.doc;
-	const $ = cheerio.load( description );
+	const $ = cheerio.load( description, null, false );
 
 	$( 'a' ).each( function() {
 		const href = $( this ).attr( 'href' );
@@ -263,7 +263,7 @@ function overridesAdapter( item ) {
 	const overrides = item.overrides || [];
 
 	return overrides.map( o => {
-		const $ = cheerio.load( o.link );
+		const $ = cheerio.load( o.link, null, false );
 
 		$( 'a' ).each( function() {
 			const href = $( this ).attr( 'href' );

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

@@ -8,7 +8,7 @@
 const fs = require( 'fs' );
 const upath = require( 'upath' );
 const glob = require( 'glob' );
-const cheerio = require( 'cheerio' );
+const { default: cheerio } = require( 'cheerio' );
 
 const SDK_SELECTOR = 'meta[name="sdk-samples"]';
 
@@ -16,7 +16,8 @@ module.exports = sourcePath => {
 	const files = [];
 	const filePaths = glob.sync( upath.join( sourcePath, '*.html' ) );
 	for ( const filePath of filePaths ) {
-		const $ = cheerio.load( fs.readFileSync( filePath, { encoding: 'utf8' } ) );
+		const content = fs.readFileSync( filePath, { encoding: 'utf8' } );
+		const $ = cheerio.load( content, null, false );
 		const samplesNames = $( SDK_SELECTOR ).attr( 'content' ) ? $( SDK_SELECTOR ).attr( 'content' ).split( '|' ) : null;
 		const samples = samplesNames ? [] : null;
 		const meta = {};

package/src/template/template-collection.js

@@ -96,7 +96,7 @@ module.exports = class TemplateCollection {
 				extractLongname,
 				getApiInfoboxTooltip,
 				capitalize,
-				relative_url
+				relative_url // eslint-disable-line camelcase
 			},
 			this._helpers,
 			this._locals

package/themes/umberto/layout/_api-docs/_mixin/_class-item.pug

@@ -22,8 +22,8 @@ mixin classItem( item )
 				p.badges
 					each badge in item.badges
 						+badge( badge )
-		div.collapsing-list__description
-			if ( item.description )
+		if ( item.description && item.description.excerpt )
+			div.collapsing-list__description
 				p( class="collapsing-list__excerpt collapsing-list__excerpt--short" )
 					| !{ item.description.excerpt }
 				+seeSource( item )

package/themes/umberto/layout/_api-docs/_mixin/_error.pug

@@ -10,8 +10,8 @@ mixin error( err )
 					a( class="member-name" href="#" + err.id ) #{ err.name }
 
 		div.collapsing-list__description.collapsing-list__description--error-page
-			p.collapsing-list__excerpt
-				if ( err.description )
+			if ( err.description && err.description.excerpt )
+				p.collapsing-list__excerpt
 					| !{ err.description.excerpt }
 
 			div.collapsing-list__content

package/themes/umberto/layout/_api-docs/_mixin/_method.pug

@@ -50,12 +50,13 @@ mixin method( met )
 						+badge( badge )
 
 		div.collapsing-list__description
-			div.collapsing-list__excerpt
-				if ( met.description )
+			if ( met.description && met.description.excerpt )
+				div.collapsing-list__excerpt
 					p !{ met.description.excerpt }
-					+seeSource( met )
 
 			div.collapsing-list__content
+				+seeSource( met )
+
 				if ( met.description )
 					| !{ met.description.content }
 

package/themes/umberto/layout/_api-docs/_mixin/_property.pug

@@ -27,12 +27,13 @@ mixin property( prop )
 						+badge( badge )
 
 		div.collapsing-list__description
-			if ( prop.description )
+			if ( prop.description && prop.description.excerpt )
 				div.collapsing-list__excerpt
 					p !{ prop.description.excerpt }
-					+seeSource( prop )
 
 			div.collapsing-list__content
+				+seeSource( prop )
+
 				if ( prop.description )
 					| !{ prop.description.content }
 

package/themes/umberto/src/css/_api-see-source.scss

@@ -26,7 +26,9 @@
 		.toggler--expanded + .collapsing-list__description {
 			.see-source {
 				display: block;
+				float: right;
 				margin-left: 50px;
+				margin-bottom: 12px;
 			}
 		}
 	}

package/themes/umberto/src/css/_collapsinglist.scss

@@ -53,6 +53,10 @@ ul.collapsing-list {
 		display: flex;
 		border-top: 1px solid u-color( 'separator' );
 
+		&--no-excerpt {
+			padding: u-spacing( -3 ) 0;
+		}
+
 		&.toggler {
 			&--collapsed,
 			&--expanded {
@@ -119,7 +123,9 @@ ul.collapsing-list {
 
 					.see-source {
 						display: block;
+						float: right;
 						margin-left: 50px;
+						margin-bottom: 12px;
 					}
 				}
 			}
@@ -173,7 +179,6 @@ ul.collapsing-list {
 	}
 
 	&__description {
-		min-height: u-spacing( 1 );
 		//padding: 0 0 0 u-spacing( 3 );
 		overflow: hidden;
 

package/themes/umberto/src/js/_collapsables.js

@@ -64,43 +64,72 @@ function enableCollapsable( options ) {
 
 export function hideTogglers() {
 	$( '.collapsing-list__item' ).each( function() {
-		const excerpt = $( this ).find( '.collapsing-list__excerpt' );
-		const term = $( this ).children( '.collapsing-list__term' );
-
+		const item = $( this );
+		const excerpt = item.find( '.collapsing-list__excerpt' );
 		const hasExcerpt = excerpt.length > 0;
 
-		// If there is no excerpt it means that API item has no description at all so we can hide the toggler.
-		if ( !hasExcerpt ) {
-			term.addClass( 'hidden' );
-
-			return;
+		if ( hasExcerpt ) {
+			hideTogglersWithExcerpts( item );
+		} else {
+			hideTogglersWithoutExcerpts( item );
 		}
+	} );
+}
 
-		const isExcerptShort = $( this ).find( '.collapsing-list__excerpt--short' ).length > 0;
+function hideTogglersWithoutExcerpts( item ) {
+	const hasDescription = item.find( '.collapsing-list__description' ).length > 0;
 
-		// Short excerpts have no togglers in the first place.
-		if ( isExcerptShort ) {
-			return;
-		}
+	// Items without description have no togglers in the first place.
+	if ( !hasDescription ) {
+		const term = item.children( '.collapsing-list__term' );
+		term.addClass( 'collapsing-list__term--no-excerpt' );
 
-		// Check whether short description is cut off by an ellipsis due to available space being too narrow.
-		const excerptParagraph = $( this ).find( '.collapsing-list__excerpt p' );
-		// Some elements have no short description, eg.:
-		// api/module_basic-styles_attributecommand-AttributeCommand.html#function-constructor
-		const excerptHasEllipsis = !excerptParagraph.length ? false :
-			Math.abs( excerptParagraph[ 0 ].clientWidth - excerptParagraph[ 0 ].scrollWidth ) > 0;
+		return;
+	}
 
-		// Check whether there is any content in the extended description.
-		const hasContent = $( this ).find( '.collapsing-list__content' ).text().trim().length > 0;
+	// Check whether there is any content in the extended description.
+	const hasContent = item.find( '.collapsing-list__content' ).text().trim().length > 0;
 
-		// Check whether there is a link to the source code.
-		const hasSourceLink = $( this ).find( '.see-source' ).length > 0;
+	// Check whether there is a link to the source code.
+	const hasSourceLink = item.find( '.see-source' ).length > 0;
 
-		// If none of the criteria above is met, toggler is not needed and can be hidden away.
-		if ( !excerptHasEllipsis && !hasContent && !hasSourceLink ) {
-			term.removeClass( classCol );
-			term.addClass( classExp );
-			term.addClass( 'hidden' );
-		}
-	} );
+	// If none of the criteria above is met, toggler is not needed and can be hidden away.
+	if ( !hasContent && !hasSourceLink ) {
+		hideTogglerForItem( item );
+	}
+}
+
+function hideTogglersWithExcerpts( item ) {
+	const isExcerptShort = item.find( '.collapsing-list__excerpt--short' ).length > 0;
+
+	// Short excerpts have no togglers in the first place.
+	if ( isExcerptShort ) {
+		return;
+	}
+
+	// Check whether short description is cut off by an ellipsis due to available space being too narrow.
+	const excerptParagraph = item.find( '.collapsing-list__excerpt p' );
+	// Some elements have no short description, eg.:
+	// api/module_basic-styles_attributecommand-AttributeCommand.html#function-constructor
+	const excerptHasEllipsis = !excerptParagraph.length ? false :
+		Math.abs( excerptParagraph[ 0 ].clientWidth - excerptParagraph[ 0 ].scrollWidth ) > 0;
+
+	// Check whether there is any content in the extended description.
+	const hasContent = item.find( '.collapsing-list__content' ).text().trim().length > 0;
+
+	// Check whether there is a link to the source code.
+	const hasSourceLink = item.find( '.see-source' ).length > 0;
+
+	// If none of the criteria above is met, toggler is not needed and can be hidden away.
+	if ( !excerptHasEllipsis && !hasContent && !hasSourceLink ) {
+		hideTogglerForItem( item );
+	}
+}
+
+function hideTogglerForItem( item ) {
+	const term = item.children( '.collapsing-list__term' );
+
+	term.removeClass( classCol );
+	term.addClass( classExp );
+	term.addClass( 'hidden' );
 }