umberto 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+## [4.1.0](https://github.com/cksource/umberto/compare/v4.0.1...v4.1.0) (2023-11-10)
+
+### Features
+
+* Umberto config file now allows `permalinkDisableDomains` array that can specify domains for which the perm-link feature should not work. Closes [#1168](https://github.com/cksource/umberto/issues/1168). ([commit](https://github.com/cksource/umberto/commit/f1370bbdb38deae3b99fb4277352bdb84cacf809))
+
+### Bug fixes
+
+* Generate a link (`{@link ...}`) to an existing type's property, resulting in a proper markup instead of displaying an error that the given structure (doclet) could not be found. Closes [#1182](https://github.com/cksource/umberto/issues/1182). ([commit](https://github.com/cksource/umberto/commit/972cb27cd81c6f1c83e1fc7cb42187782a60a58f))
+
+
 ## [4.0.1](https://github.com/cksource/umberto/compare/v4.0.0...v4.0.1) (2023-10-16)
 
 ### Bug fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [

package/scripts/filter/before-post-render/add-project-info-to-page.js

@@ -36,6 +36,7 @@ hexo.extend.filter.register( 'before_post_render', page => {
 	page.groupId = category ? category.groupId : null;
 	page.groupSlug = category ? category.groupSlug : null;
 	page.shortName = upath.basename( page.source ).replace( upath.extname( page.source ), '' );
+	page.permalinkDisableDomains = projectGlobals.config.permalinkDisableDomains.join( ',' );
 
 	if ( hexo.projectGlobals.common.isSingleProject && projectGlobals.config.canonicalUrlBeginning ) {
 		page.canonicalUrlBeginning = projectGlobals.config.canonicalUrlBeginning;

package/scripts/utils/parselinks.js

@@ -147,7 +147,15 @@ function linkToApi( str, data, hexo, { relativeUrlHelper, isSilentError } ) {
 	}
 
 	if ( hasDedicatedApiPages( targetDoclet ) ) {
-		href = relativeUrlHelper( data.path, upath.join( basePath, apiSlug, getFileName( itemName ) ) );
+		let propertyName = itemName;
+
+		// Properties of `type` do not have own doclets. Instead, they are specified as `properties` in the `type`
+		// (parent) doclet. Hence, we must link to it manually. See: #1182.
+		if ( targetDoclet.kind === 'typedef' ) {
+			propertyName = propertyName.replace( '#', '#member-' );
+		}
+
+		href = relativeUrlHelper( data.path, upath.join( basePath, apiSlug, getFileName( propertyName ) ) );
 	} else {
 		href = [
 			relativeUrlHelper( data.path, upath.join( basePath, apiSlug, fileName ) ),
@@ -189,7 +197,15 @@ function getBaseItemName( itemName ) {
 }
 
 function getFileName( itemName ) {
-	return itemName.replace( /[/:.]/g, '_' ).replace( '~', '-' ) + '.html';
+	const output = itemName.replace( /[/:.]/g, '_' ).replace( '~', '-' );
+	const [ fileNameWithHash, extension = 'html' ] = output.split( '.' );
+	const [ fileName, hash ] = fileNameWithHash.split( '#' );
+
+	if ( hash ) {
+		return `${ fileName }.${ extension }#${ hash }`;
+	}
+
+	return `${ fileName }.${ extension }`;
 }
 
 function getOutputLink( href, description, isCustomDescription ) {

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

@@ -249,6 +249,12 @@ module.exports = class DescriptionParser {
 
 				if ( hasDedicatedApiPages( targetDoclet ) ) {
 					href = this._fileNameManager.getUrl( targetDoclet.longname );
+
+					// Properties of `type` do not have own doclets. Instead, they are specified as `properties` in the `type`
+					// (parent) doclet. Hence, we must link to it manually. See: #1182.
+					if ( this._hasMember( targetDoclet, member ) ) {
+						href += `#member-${ member }`;
+					}
 				} else {
 					href = [
 						this._fileNameManager.getUrl( targetDoclet.memberof ),
@@ -289,6 +295,26 @@ module.exports = class DescriptionParser {
 		return result;
 	}
 
+	/**
+	 * @protected
+	 * @param {Object} typedef
+	 * @param {String} typedef.kind
+	 * @param {Array.<Object>} [typedef.properties]
+	 * @param {String} propertyName
+	 * @returns {Boolean}
+	 */
+	_hasMember( typedef, propertyName ) {
+		if ( typedef.kind !== 'typedef' ) {
+			return false;
+		}
+
+		if ( !Array.isArray( typedef.properties ) ) {
+			return false;
+		}
+
+		return !!typedef.properties.find( item => item.name === propertyName );
+	}
+
 	/**
 	 * Changes headings in description to smaller. Allowed headings are h3-h6.
 	 * If in source code commments h1, h2 heading are used, they need to be lowered.

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

@@ -67,7 +67,21 @@ module.exports = function findTargetDoclet( docletCollection, options ) {
 	}
 
 	if ( collection.isEmpty ) {
-		return null;
+		const typedefCollection = collection = docletCollection.get( `ln:${ structure }` );
+
+		if ( typedefCollection.isEmpty ) {
+			return null;
+		}
+
+		const typedefItem = typedefCollection.getFirst();
+
+		if ( typedefItem.kind !== 'typedef' ) {
+			return null;
+		}
+
+		const { properties = [] } = typedefItem;
+
+		return properties.find( item => item.name === member ) ? typedefItem : null;
 	}
 
 	let targetDoclet;

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

@@ -290,11 +290,12 @@ class TypedocConverter {
 			const childSignature = child.kindString === 'Method' ? child.signatures[ 0 ] : child;
 			const response = this._convertTypeToJsDoc( childSignature );
 
+			// For all properties, explicitly create the `id` key (as `extraId` key).
+			// The `id` is then used to create the `longname` key. Unfortunately, nested properties are processed manually,
+			// so part of the parser's job must be done here.
+			response.extraId = `member-${ childSignature.name }`;
+
 			if ( child.kindString === 'Index signature' ) {
-				// For computed property (stored as index signature by TypeDoc), explicitly create the `id` key (as `extraId` key).
-				// The `id` is then used to created the `longname` key. Otherwise, the `id` and `longname` keys would be created
-				// automatically later and they would contain computed name in their values.
-				response.extraId = `member-${ childSignature.name }`;
 				response.name = TypedocConverter.getComputedName( childSignature );
 			} else {
 				response.name = childSignature.name;

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

@@ -37,6 +37,8 @@ block navtree
     != navTree
 
 block projectVersion
+    meta( name= 'permalink-disable-domains' content=page.permalinkDisableDomains )
+
     if projectLocals
         meta( name= 'project-version' content= projectLocals.projectVersion )
         meta( name= 'project-slug' content= projectLocals.projectSlug )

package/themes/umberto/layout/api.pug

@@ -19,6 +19,8 @@ block append content
 		include _partial/report-issue-widget
 
 block projectVersion
+	meta( name= 'permalink-disable-domains' content=page.permalinkDisableDomains )
+
 	if projectLocals
 		meta( name= 'project-version' content= projectLocals.projectVersion )
 		meta( name= 'project-slug' content= projectLocals.projectSlug )

package/themes/umberto/layout/page.pug

@@ -21,6 +21,8 @@ block navtree
 	include _partial/nav-tree
 
 block projectVersion
+	meta( name= 'permalink-disable-domains' content=page.permalinkDisableDomains )
+
 	if projectLocals
 		meta( name= 'project-version' content= projectLocals.projectVersion )
 		meta( name= 'project-slug' content= projectLocals.projectSlug )

package/themes/umberto/layout/sdk.pug

@@ -21,6 +21,8 @@ block navtree
 						!= projectLocals.sdkNavTree
 
 block projectVersion
+	meta( name= 'permalink-disable-domains' content=page.permalinkDisableDomains )
+
 	if projectLocals
 		meta( name= 'project-version' content= projectLocals.projectVersion )
 		meta( name= 'project-slug' content= projectLocals.projectSlug )

package/themes/umberto/src/js/_attachpermalinklistener.js

@@ -11,6 +11,16 @@ export default function attachPermalinkListener() {
 		return;
 	}
 
+	const permalinkDisableDomainsElement = document.querySelector( 'meta[name=permalink-disable-domains]' );
+
+	if ( permalinkDisableDomainsElement ) {
+		const permalinkDisableDomains = permalinkDisableDomainsElement.getAttribute( 'content' ).split( ',' );
+
+		if ( permalinkDisableDomains.includes( location.hostname ) ) {
+			return;
+		}
+	}
+
 	const projectVersion = projectVersionElement.getAttribute( 'content' );
 	const projectSlug = projectSlugElement.getAttribute( 'content' );