umberto 2.0.2 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "2.0.2",
+  "version": "2.1.2",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -16,7 +16,7 @@
     "@babel/core": "^7.10.3",
     "@babel/polyfill": "^7.10.1",
     "@babel/preset-env": "^7.10.3",
-    "@ckeditor/jsdoc-plugins": "^27.1.1",
+    "@ckeditor/jsdoc-plugins": "^30.1.4",
     "babel-loader": "^8.1.0",
     "chalk": "^4.1.0",
     "cheerio": "^0.22.0",
@@ -42,6 +42,7 @@
     "medium-zoom": "^1.0.5",
     "mkdirp": "^1.0.4",
     "moment": "^2.27.0",
+    "minimatch": "^3.1.2",
     "nyc": "15.1.0",
     "pug": "^3.0.0",
     "sass": "^1.43.4",
@@ -53,7 +54,7 @@
     "webpack": "^5.58.1"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-dev-env": "^27.3.0",
+    "@ckeditor/ckeditor5-dev-env": "^30.1.4",
     "browser-sync": "^2.26.7",
     "chai": "^4.3.4",
     "chokidar": "^3.4.0",
@@ -75,7 +76,7 @@
     "dev:serve": "node ./scripts-dev/serve.js",
     "lint": "eslint --quiet '**/*.js'",
     "test": "mocha tests --recursive",
-    "coverage": "nyc --reporter=lcov --reporter=text-summary mocha tests/ -- --recursive",
+    "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"

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

@@ -7,6 +7,7 @@
 
 const upath = require( 'upath' );
 const shouldDisplayNewIndicator = require( '../../utils/shoulddisplaynewindicator' );
+const getReportIssueWidgetUrl = require( '../../utils/getreportissuewidgeturl' );
 
 /**
  * Adds project information (e.g. BASE_PATH, project name, group id) to each page.
@@ -42,6 +43,9 @@ hexo.extend.filter.register( 'before_post_render', page => {
 
 	page.shouldDisplayNewIndicator = shouldDisplayNewIndicator( page );
 
+	// This line needs to be sync with the `src/api-builder/api-builder.js` file.
+	page.reportIssueWidget = getReportIssueWidgetUrl( page, projectGlobals.config );
+
 	return page;
 }, 3 );
 

package/scripts/utils/getreportissuewidgeturl.js

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const minimatch = require( 'minimatch' );
+
+/**
+ * @param {Object} page A page object.
+ * @param {String} page.path A relative path where a page will be stored.
+ * @param {Object} config The project configuration.
+ * @param {Object} config.reportIssueWidget The report issue widget configuration.
+ * @param {Boolean} config.reportIssueWidget.enabled Whether the report issue widget is enabled.
+ * @param {Array.<String>} config.reportIssueWidget.skipPages An array of glob patterns that define pages where
+ * the report issue widget should be disabled.
+ * @param {String} config.reportIssueWidget.issueUrl The URL that leads to a form where a user can create a new issue.
+ * @return {String|null}
+ */
+module.exports = function getReportIssueWidgetUrl( page, config ) {
+	if ( !config.reportIssueWidget.enabled ) {
+		return null;
+	}
+
+	const isAllowedOnPage = !config.reportIssueWidget.skipPages.some( pattern => {
+		// Map a pattern to: `<slug>/<version>/<path>`.
+		const globPatern = config.slug + '/*/' + pattern;
+
+		return minimatch( page.path, globPatern );
+	} );
+
+	if ( !isAllowedOnPage ) {
+		return null;
+	}
+
+	return config.reportIssueWidget.issueUrl;
+};

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

@@ -18,6 +18,7 @@ const getShortModulePath = require( '../helpers/get-short-module-path' );
 const getDocSearchConfig = require( '../helpers/get-docsearch-config' );
 const splitLongname = require( '../helpers/split-longname' );
 const githubUrlUtils = require( '../helpers/github-url' );
+const getReportIssueWidgetUrl = require( '../../scripts/utils/getreportissuewidgeturl' );
 
 /**
  * Renders HTML for every module, class, mixin etc.
@@ -424,6 +425,10 @@ module.exports = class ApiBuilder {
 					'twitter-card': trimDescription( { min: 300, max: 600, text: metaDescription } ),
 					'dc-description': trimDescription( { min: 300, max: 600, text: metaDescription } )
 				};
+
+				// This line needs to be sync with the `scripts/filter/before-post-render/add-project-info-to-page.js` file.
+				page.reportIssueWidget = getReportIssueWidgetUrl( page, this._projectConfig );
+
 				// More locals to be used in templates. Matching locals used by hexo.
 				const projectLocals = {
 					latestBasePath: upath.join( this._projectSlug, 'latest' ),
@@ -432,6 +437,7 @@ module.exports = class ApiBuilder {
 					getLinkToSource: githubUrlUtils.getFullGithubLink.bind( this ),
 					docSearchConfig: getDocSearchConfig( this._docSearch, {
 						groups: this._groups,
+						slug: this._projectSlug,
 						customRanking: this._projectConfig.docsearch ? this._projectConfig.docsearch.customRanking : []
 					} )
 				};

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

@@ -10,6 +10,7 @@ const { cloneDeep } = require( 'lodash' );
 
 module.exports = ( searchConfig, {
 	groups = [],
+	slug = '',
 	customRanking = []
 } = {} ) => {
 	if ( !searchConfig ) {
@@ -53,7 +54,7 @@ module.exports = ( searchConfig, {
 		].join( '\n' )
 	};
 
-	const transformDataFunctions = getTransformDataFns( groups );
+	const transformDataFunctions = getTransformDataFns( groups, slug );
 
 	if ( transformDataFunctions ) {
 		for ( const tag of Object.keys( transformDataFunctions ) ) {
@@ -86,7 +87,7 @@ module.exports = ( searchConfig, {
 	return docSearchConfig;
 };
 
-function getTransformDataFns( groups ) {
+function getTransformDataFns( groups, slug ) {
 	if ( !Array.isArray( groups ) || groups.length === 0 ) {
 		return null;
 	}
@@ -114,7 +115,7 @@ function getTransformDataFns( groups ) {
 
 			`hitsGrouped[ '${ g.slug }' ] = hits`,
 			'.filter( function( h ) {',
-			`return h.tags.includes( '${ g.slug }' );`,
+			`return h.tags.includes( '${ slug }' ) && h.tags.includes( '${ g.slug }' );`,
 			'} )',
 			'.slice( 0, 7 )',
 			'.map( function( item, idx ) {',
@@ -127,7 +128,7 @@ function getTransformDataFns( groups ) {
 			`if ( tag !== '${ g.slug }' ) {`,
 			'hitsGrouped[ tag ] = hits',
 			'.filter( function( h ) {',
-			'return h.tags.includes( tag );',
+			`return h.tags.includes( '${ slug }' ) && h.tags.includes( tag );`,
 			'} )',
 			'.slice( 0, 10 )',
 			'.map( function( item, idx ) {',
@@ -188,7 +189,7 @@ function getTransformDataFns( groups ) {
 		'tags.forEach( function( tag ) {',
 		'hitsGrouped[ tag ] = hits',
 		'.filter( function( h ) {',
-		'return h.tags.includes( tag );',
+		`return h.tags.includes( '${ slug }' ) && h.tags.includes( tag );`,
 		'} )',
 		'.slice( 0, 10 )',
 		'.map( function( item, idx ) {',

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

@@ -63,6 +63,7 @@ module.exports = ( ctx, {
 				disableSearch: config.docsearch === false,
 				docSearchConfig: getDocSearchConfig( docSearch, {
 					groups: config.groups,
+					slug: config.slug,
 					customRanking: config.docsearch ? config.docsearch.customRanking : []
 				} ),
 				repoUrl: config.repoUrl,

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

@@ -156,6 +156,7 @@ module.exports = class SdkBuilder {
 				projectSlug,
 				docSearchConfig: getDocSearchConfig( this._docSearch, {
 					groups: this.projectConfig.groups,
+					slug: this.projectConfig.slug,
 					customRanking: this.projectConfig.docsearch ? this.projectConfig.docsearch.customRanking : []
 				} )
 			};

package/src/tasks/get-project-config.js

@@ -9,6 +9,8 @@ const upath = require( 'upath' );
 const fs = require( 'fs' );
 const glob = require( 'glob' );
 
+const cache = new Map();
+
 /**
  * Reads project's umberto.json config, validates it and adds various properties.
  *
@@ -18,7 +20,15 @@ const glob = require( 'glob' );
  * @returns {Object}
  */
 module.exports = ( rootPath, options = {} ) => {
+	// Let's normalize the root path to fix mixed slashes and backslashes. Root path should contain only slashes.
+	rootPath = rootPath.split( /[\\/]/g ).join( '/' );
+
 	const configPath = findConfigurationPath( rootPath );
+
+	if ( cache.has( configPath ) ) {
+		return cache.get( configPath );
+	}
+
 	const config = getConfigurationFile( configPath );
 
 	config.__configPath = configPath;
@@ -58,6 +68,22 @@ module.exports = ( rootPath, options = {} ) => {
 		} );
 	}
 
+	// If the "reportIssueWidget" is missing, let's add. Default values will be filled in next steps.
+	if ( !config.reportIssueWidget ) {
+		config.reportIssueWidget = {};
+	}
+
+	// Prepare default values.
+	config.reportIssueWidget.enabled = config.reportIssueWidget.enabled || false;
+	config.reportIssueWidget.skipPages = config.reportIssueWidget.skipPages || [];
+
+	// And check whether the `issueUrl` is available if the widget is enabled.
+	if ( config.reportIssueWidget.enabled && !config.reportIssueWidget.issueUrl ) {
+		throw new Error(
+			`[${ config.name }]: The "reportIssueWidget.issueUrl" value must be specified if the report issue widget is enabled.`
+		);
+	}
+
 	validateConfiguration( config );
 
 	config.version = getProjectVersion( rootPath );
@@ -67,6 +93,9 @@ module.exports = ( rootPath, options = {} ) => {
 	// Packages of the project. Packages can have their own guides and they need to be included in the documentation.
 	config.items = config.items || getPackages( rootPath, config.slug, config.packagesDir );
 
+	// Store the configuration.
+	cache.set( configPath, config );
+
 	return config;
 };
 
@@ -122,8 +151,7 @@ function loadScriptToConfig( config, options ) {
 		return;
 	}
 
-	const scriptKey = options.scriptKey;
-	const configKey = options.configKey;
+	const { scriptKey, configKey } = options;
 
 	// Do not load anything if the script is not specified in the configuration file.
 	if ( !config.scripts[ scriptKey ] ) {

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

@@ -33,5 +33,8 @@ block content
 
     include _partial/functions
 
+    if page.reportIssueWidget
+        include ../_partial/report-issue-widget
+
 block navtree
     != navTree

package/themes/umberto/layout/_partial/report-issue-widget.pug

@@ -0,0 +1,22 @@
+//- Remove the "project-slug/version/" from the path.
+- const shortPageUrl = page.path.split( '/' ).slice( 2 ).join( '/' )
+- const githubUrl = new URL( page.reportIssueWidget );
+- githubUrl.searchParams.set( 'title', 'Docs issue report from "' + shortPageUrl + '"' );
+
+div.info-box.notice.notice__feedback
+    p
+        | Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing?
+        | Please report it via our!{' '}
+        a( href=githubUrl.toString() id='report-widget-issue-tracker' ) issue tracker
+        | .
+
+//- We need to inject some parameters to the URL from the `window` object on the user side.
+//- Hence, we run a script that reads the user-agent and location and injects it into the issue URL.
+script.
+    ( () => {
+        const issueTracker = document.getElementById( 'report-widget-issue-tracker' );
+        const hrefUrl = new URL( issueTracker.href );
+        hrefUrl.searchParams.set( 'user-agent', navigator.userAgent )
+        hrefUrl.searchParams.set( 'origin-url', location.href )
+        issueTracker.href = hrefUrl.toString();
+    } )();

package/themes/umberto/layout/api.pug

@@ -9,6 +9,9 @@ block content
 
 	!= split.content
 
+	if page.reportIssueWidget
+		include _partial/report-issue-widget
+
 block navtree
 	if projectLocals && projectLocals.apiTree
 		!= projectLocals.apiTree

package/themes/umberto/layout/page.pug

@@ -12,5 +12,8 @@ block content
 
 	!= split.content
 
+	if page.reportIssueWidget
+		include _partial/report-issue-widget
+
 block navtree
 	include _partial/nav-tree

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

@@ -55,6 +55,10 @@ p.tip {
 		border-left: 3px solid u-color( 'hint-info' );
 	}
 
+	&__feedback {
+	  	border-left: 3px solid u-color( 'hint-hint' );
+	}
+
 	&__warning {
 		border-left: 3px solid u-color( 'hint-warning' );
 		background-color: rgba( u-color( 'hint-warning' ), .1 );