umberto 7.0.2 → 8.0.0

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

@@ -51,6 +51,6 @@ hexo.extend.filter.register( 'before_post_render', page => {
 	page.reportIssueWidget = getReportIssueWidgetUrl( page, projectGlobals.config );
 
 	return page;
-}, 3 );
+}, 1 );
 
 // The lower the priority the sooner a filter is executed.

package/scripts/filter/before-post-render/code-switcher.js

@@ -12,5 +12,9 @@ const transformCodeSwitcher = require( '../../utils/transformcodeswitcher' );
  * Tag syntax is <code-switcher>```js ```</code-switcher>.
  */
 hexo.extend.filter.register( 'before_post_render', data => {
+	if ( data.projectTheme === 'gloria' ) {
+		return data;
+	}
+
 	return transformCodeSwitcher( data, hexo );
 } );

package/scripts/filter/before-post-render/execute-and-insert-function-results.js

@@ -16,7 +16,9 @@ const executeAndInsertFunctionResults = require( '../../utils/execute-and-insert
  * It will be processed by Hexo when building the documentation.
  *
  * Asynchronous functions are not supported by Hexo, so the callback must be synchronous.
+ *
+ * Make sure it's executed before prerendering of gloria components.
  */
 hexo.extend.filter.register( 'before_post_render', page => {
 	return executeAndInsertFunctionResults( page, hexo );
-} );
+}, 6 );

package/scripts/filter/before-post-render/gloria/add-breadcrumbs-data-to-page.js

@@ -0,0 +1,269 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const upath = require( 'upath' );
+const decodeHtmlEntities = require( '../../../utils/decode-html-entities' );
+const dropUrlProtocol = require( '../../../utils/drop-url-protocol' );
+const concatUrlParts = require( '../../../utils/concat-url-parts' );
+const relative_url = require( 'hexo/dist/plugins/helper/relative_url' ); // eslint-disable-line camelcase
+const dropInitSlash = require( '../../../utils/drop-init-slash' );
+
+/**
+ * Adds breadcrumbs data to the page by finding links to parent categories.
+ *
+ * Each category typically has an index.md file which contains an "Overview" page.
+ * These overview pages are treated as index pages for their respective categories.
+ *
+ * The filter traverses up the category hierarchy and builds breadcrumbs from:
+ * - Parent category overview pages (using the "Overview" pages as targets)
+ * - Group index pages for top-level categories
+ * - The current page being rendered
+ */
+hexo.extend.filter.register( 'before_post_render', page => {
+	if ( page.projectTheme !== 'gloria' ) {
+		return;
+	}
+
+	const [ projectName ] = page.path.split( '/' );
+	const projectGlobals = hexo.projectGlobals?.[ projectName ];
+
+	if ( !projectGlobals || !page.category ) {
+		page.breadcrumbs = {
+			items: [],
+			jsonLd: null
+		};
+
+		return page;
+	}
+
+	const { categoryIds, config } = projectGlobals;
+
+	const basePath = hexo.projectGlobals[ page.projectName ].BASE_PATH;
+	const pages = hexo.model( 'Page' ).toArray();
+
+	// Get all categories and groups from the project globals.
+	const categoriesBreadcrumbs = getAllParentCategories( categoryIds, page.category )
+		.map( ( categoryOrGroup, index, array ) => {
+			const { category, groupId } = categoryOrGroup;
+
+			if ( category === null ) {
+				const extendedGroup = projectGlobals.groups.find( g => g.id === groupId );
+				const path = (
+					extendedGroup?._url ?
+						upath.join( '/', basePath, extendedGroup.slug, 'index.html' ) :
+						null
+				);
+
+				return {
+					path,
+					name: extendedGroup?.name,
+					active: false
+				};
+			}
+
+			// It turns out that `page.path` is not always the correct one.
+			// Umberto might generate incorrect page path when the page file
+			// is placed within directory of another category but is mapped
+			// to the different category in `umberto.json`.
+			const path = ( () => {
+				const overviewPage = pages.find(
+					nestedPage =>
+						nestedPage.category === category.id &&
+						isOverviewPage( nestedPage )
+				);
+
+				if ( !overviewPage?.path ) {
+					return null;
+				}
+
+				const filename = upath.basename( overviewPage.path );
+				const slugs = array
+					.slice( 0, index + 1 )
+					.map( item => item.category?.slug ?? item.groupSlug )
+					.filter( Boolean );
+
+				return upath.join( '/', basePath, ...slugs, filename );
+			} )();
+
+			return {
+				path,
+				name: category.name,
+				active: false
+			};
+		} )
+		.filter( page => page?.name?.length > 0 );
+
+	// Prepend home and current page. Make sure that we have absolute URLs.
+	const breadcrumbs = [
+		{
+			path: upath.join( '/', basePath, 'index.html' ),
+			name: 'Home',
+			active: false
+		},
+		...categoriesBreadcrumbs,
+		{
+			path: upath.join( '/', page.path ),
+			name: getPageTitle( page ),
+			active: true
+		}
+	]
+		.map( item => {
+			const newLatestPath = item.path?.replace( config.version, 'latest' );
+
+			if ( !newLatestPath || !page.canonicalUrlBeginning ) {
+				return item;
+			}
+
+			const url = concatUrlParts( `https://${ dropUrlProtocol( page.canonicalUrlBeginning ) }`, newLatestPath );
+			const relativePath = relative_url( page.path, dropInitSlash( item.path ) );
+
+			return {
+				...item,
+				path: relativePath,
+				url
+			};
+		} )
+		.reduce( ( result, currentItem, index, array ) => {
+			if ( index &&
+					array[ index - 1 ].url === currentItem.url &&
+					( isOverviewPage( currentItem.name ) || isIndexPage( currentItem ) ) ) {
+				array[ index - 1 ].active = array[ index ].active;
+				return result;
+			}
+
+			result.push( currentItem );
+			return result;
+		}, [] );
+
+	page.breadcrumbs = {
+		items: breadcrumbs,
+		jsonLd: generateBreadcrumbsJsonLd( breadcrumbs )
+	};
+
+	return page;
+}, 10 );
+
+/**
+ * Generates schema.org JSON-LD structured data for breadcrumbs.
+ *
+ * @param breadcrumbs Array of breadcrumb items
+ * @returns JSON-LD object for breadcrumbs
+ */
+function generateBreadcrumbsJsonLd( breadcrumbs ) {
+	const validItems = breadcrumbs.filter( item => item.url );
+
+	if ( !validItems.length ) {
+		return null;
+	}
+
+	return {
+		'@context': 'https://schema.org',
+		'@type': 'BreadcrumbList',
+		'itemListElement': validItems.map( ( item, index ) => ( {
+			'@type': 'ListItem',
+			'position': index + 1,
+			'name': item.name,
+			'item': item.url
+		} ) )
+	};
+}
+
+/**
+ * Check if the page is an index page.
+ * An index page is typically the overview page for a category.
+ */
+function isIndexPage( page ) {
+	return page.path?.endsWith( 'index.html' );
+}
+
+/**
+ * Check if the page is an overview page.
+ */
+function isOverviewPage( pageOrTitle ) {
+	if ( typeof pageOrTitle !== 'string' ) {
+		pageOrTitle = getPageTitle( pageOrTitle );
+	}
+
+	return pageOrTitle.trim().toLowerCase().includes( 'overview' );
+}
+
+/**
+ * Get the page title.
+ */
+function getPageTitle( page ) {
+	return page[ 'menu-title' ] || tryExtractTitleFromMarkdown( page.content ) || page.title;
+}
+
+/**
+ * Try to extract the title from the markdown content.
+ * Searches for the first level 1 header (# Title) anywhere in the content.
+ */
+function tryExtractTitleFromMarkdown( content ) {
+	if ( !content ) {
+		return null;
+	}
+
+	// Look for the first # header anywhere in the content
+	const lines = content.split( '\n' );
+
+	for ( const line of lines ) {
+		const headerMatch = line.match( /^\s*#\s+(.+)$/ );
+
+		if ( headerMatch ) {
+			const rawTitle = headerMatch[ 1 ].trim();
+
+			// Decode HTML entities in the title
+			return decodeHtmlEntities( rawTitle );
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Get all parent categories of a given category (including the category itself).
+ * Max 20 iterations to avoid infinite loops due to clunky data.
+ *
+ * @returns Array of category objects sorted from the deepest (child) to the top-level (parent).
+ *
+ * @example
+ * ```js
+ * [
+ *	// ...
+ *	{
+ *		categoryId: 'framework-deep-dive',
+ *		parentCategoryId: 'framework',
+ *		groupId: 'framework',
+ *		groupSlug: 'framework',
+ *		path: 'ckeditor5/45.0.0/framework/deep-dive'
+ *	},
+ *	{
+ *		categoryId: null,
+ *		parentCategoryId: null,
+ *		groupId: 'framework',
+ *		groupSlug: 'framework',
+ *		path: 'ckeditor5/45.0.0/framework'
+ *	}
+ * ]
+ * ```
+ */
+function getAllParentCategories( allCategoriesMap, category ) {
+	const buildPath = ( categoryId, path = [] ) => {
+		if ( !categoryId || path.length >= 20 ) {
+			return path;
+		}
+
+		const category = allCategoriesMap.get( categoryId );
+		if ( !category ) {
+			return path;
+		}
+
+		return buildPath( category.parentCategoryId, [ category, ...path ] );
+	};
+
+	return buildPath( category );
+}

package/scripts/filter/before-post-render/gloria/prerender-admonitions.js

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const {
+	transformMarkdownAdmonitions,
+	fastCheckIfContainsAdmonition
+} = require( '../../../utils/transform-markdown-admonitions' );
+
+/**
+ * Make sure it's executed after `execute-and-insert-function-results.js` filter.
+ */
+hexo.extend.filter.register( 'before_post_render', page => {
+	if ( page.projectTheme !== 'gloria' || !page.content || !fastCheckIfContainsAdmonition( page.content ) ) {
+		return page;
+	}
+
+	const renderedAdmonition = ( { type, content } ) =>
+		`<info-box ${ type.toLowerCase() }>\n${ content.join( '\n' ) }\n</info-box>`;
+
+	page.content = transformMarkdownAdmonitions( renderedAdmonition, page.content );
+
+	return page;
+}, 7 );

package/scripts/filter/before-post-render/gloria/prerender-xml-pug-components.js

@@ -0,0 +1,339 @@
+/**
+ * @license Copyright (c) 2017-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * This script converts XML-like custom component syntax in Markdown files to Pug templates.
+ * It allows writers to use an intuitive HTML-like syntax in documentation while leveraging
+ * the power of Pug mixins for rendering complex UI components.
+ *
+ * The process works in two steps:
+ * 1. Before markdown rendering: Components are identified, processed, and replaced with UUID markers
+ * 2. After markdown rendering: UUID markers are replaced with the fully rendered components
+ *
+ * This two-phase approach is necessary because Markdown processors often misinterpret HTML
+ * indentation and nested structures, leading to unwanted paragraph breaks, incorrect
+ * formatting, or stripped content. By temporarily replacing components with simple markers,
+ * we avoid Markdown interference with our component HTML structure.
+ *
+ * For example:
+ *   <ck:badge variant="premium" /> becomes +badge({ variant: 'premium' })
+ *   <ck:button label="Click me" icon="github" /> becomes +button({ label: 'Click me', icon: 'github' })
+ *
+ * It allows binding slots to components, so that the content of a component can be passed as a slot.
+ *
+ * For example:
+ *   <ck:tabs>
+ *     <ck:tab id="desktop" label="Desktop" active="true">
+ *       TAB
+ *     </ck:tab>
+ *     <ck:tab id="mobile" label="Mobile">
+ *       Use the **main menu button in the upper-left corner** to navigate through the documentation.
+ *     </ck:tab>
+ *   </ck:tabs>
+ * becomes:
+ *   +tabs()
+ *     +tab({ id: 'desktop', label: 'Desktop', active: true })
+ *       | TAB
+ *     +tab({ id: 'mobile', label: 'Mobile' })
+ *       | Use the <strong>main menu button in the upper-left corner</strong> to navigate through the documentation.
+ */
+
+'use strict';
+
+const path = require( 'path' );
+const removeIndentation = require( '../../../utils/remove-indentation' );
+const createPrerenderPugTemplate = require( '../../../utils/pug-renderer/create-prerender-pug-template' );
+const {
+	renderXMLPugComponentsInMarkdown,
+	extractReplacementBase64Tag
+} = require( '../../../utils/pug-to-xml-binding/render-xml-pug-components-in-markdown' );
+
+const PATTERN_ELEMENTS = [
+	// Info boxes
+	{
+		pattern: /^(?:ck:)?info-box$/,
+		mixinName: 'callout',
+		allowMarkdownContent: true,
+		requires: [
+			'_components/svg/index',
+			'_components/icon/index',
+			'_components/icon-message/index',
+			'_components/callout/index'
+		],
+		attributesMapper: ( { attributes } ) => {
+			const variants = [
+				'info', 'warning', 'error', 'success',
+				'note', 'tip', 'important', 'caution'
+			];
+
+			// First check if variant is directly specified
+			if ( attributes.variant && variants.includes( attributes.variant ) ) {
+				return {
+					variant: attributes.variant
+				};
+			}
+
+			// Otherwise check if any variant name is used as an attribute
+			const foundVariant = variants.find( v => v in attributes );
+
+			return {
+				variant: foundVariant || 'info'
+			};
+		}
+	},
+
+	// Tabs
+	{
+		pattern: 'ck:tabs',
+		mixinName: 'tabs'
+	},
+	{
+		pattern: 'ck:tab',
+		mixinName: 'tab',
+		allowMarkdownContent: true
+	},
+
+	// Code tabs
+	{
+		pattern: 'ck:code-switcher-tabs',
+		mixinName: 'code-switcher'
+	},
+
+	// Banner
+	{
+		pattern: 'ck:banner',
+		mixinName: 'banner',
+		allowMarkdownContent: true
+	},
+
+	// Icons
+	{
+		pattern: 'ck:svg',
+		mixinName: 'inline-svg',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/svg/index'
+		]
+	},
+	{
+		pattern: 'ck:spritesheet-svg',
+		mixinName: 'spritesheet-local-svg',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/svg/index'
+		]
+	},
+	{
+		pattern: 'ck:preload-spritesheet-svg',
+		mixinName: 'preload-spritesheet-svg',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/svg/index'
+		]
+	},
+	{
+		pattern: 'ck:preload-svg-spritesheet-icon',
+		mixinName: 'preload-svg-spritesheet-icon',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/svg/index',
+			'_components/icon/index'
+		]
+	},
+
+	// Code block
+	{
+		pattern: 'ck:code-block',
+		attributesMapper: node => {
+			if ( node.attributes.code ) {
+				return node.attributes;
+			}
+
+			const content = removeIndentation(
+				node.children
+					.join( '\n' ).trim()
+					.replace( /^\|[\s]+/, '' )
+			);
+
+			node.children = [];
+
+			return {
+				...node.attributes,
+				code: content || null
+			};
+		},
+
+		// Custom renderer is used to optimize rendering of the code block component.
+		// There is hundreds of code blocks in the documentation, and we want to avoid
+		// rendering them for each page.
+		renderer: ( () => {
+			const template = createPrerenderPugTemplate( {
+				hexo,
+				requires: [
+					'_components/svg/index',
+					'_components/icon/index',
+					'_components/tooltip-popover/index',
+					'_components/skeleton/index',
+					'_components/code-block/index'
+				],
+				component: 'code-block',
+				skipCacheIf: ( { code } ) => code?.split( '\n' ).length > 1,
+				componentAttrs: {
+					static: {
+						copyable: true
+					},
+					dynamic: [ 'copyable', 'language' ],
+					mask: [ 'code' ]
+				}
+			} );
+
+			return ( { attributes } ) => template( attributes );
+		} )()
+	},
+	{
+		pattern: /^(?:ck:)?code-switcher$/,
+		mixinName: 'cke5-code-switcher',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/svg/index',
+			'_components/icon/index',
+			'_components/tooltip-popover/index',
+			'_components/skeleton/index',
+			'_components/code-block/index',
+			'_components/tabs/index',
+			'_components/code-switcher/index',
+			'_components/cke5-code-switcher/index'
+		],
+
+		// Transform content into attribute, as pug does't play well with preformatted code.
+		attributesMapper: node => {
+			const content = removeIndentation(
+				node.children
+					.join( '\n' ).trim()
+					.replace( /^\|[\s]+/, '' )
+			);
+
+			node.children = [];
+
+			return {
+				...node.attributes,
+				code: content || null
+			};
+		}
+	},
+
+	// Card
+	{
+		pattern: /^(?:ck:)?card$/,
+		mixinName: 'card',
+		allowMarkdownContent: true,
+		requires: [
+			'_components/svg/index',
+			'_components/icon/index',
+			'_components/card/index'
+		]
+	},
+	{
+		pattern: 'ck:card-description',
+		mixinName: 'card-description',
+		allowMarkdownContent: true
+	},
+	{
+		pattern: 'ck:card-footer',
+		mixinName: 'card-footer',
+		allowMarkdownContent: true
+	},
+	{
+		pattern: 'ck:card-learn-more',
+		mixinName: 'card-learn-more',
+		allowMarkdownContent: true
+	},
+
+	{
+		pattern: 'ck:columns',
+		mixinName: 'columns',
+		allowMarkdownContent: true,
+		requires: [
+			'_components/columns/index'
+		]
+	},
+
+	// Heading badge
+	{
+		pattern: 'ck:heading-badge',
+		mixinName: 'heading-badge',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/heading-badge/index',
+			'_components/badge/index',
+			'_components/svg/index',
+			'_components/icon/index',
+			'_components/tooltip-popover/index'
+		]
+	},
+	{
+		pattern: 'ck:badge',
+		mixinName: 'badge',
+		allowMarkdownContent: false,
+		requires: [
+			'_components/svg/index',
+			'_components/icon/index',
+			'_components/tooltip-popover/index',
+			'_components/badge/index'
+		]
+	},
+
+	// Dynamic match pattern
+	{
+		pattern: /ck:[\w-]+/,
+		map: node => {
+			const [ , mixinName ] = node.name.split( ':' );
+
+			return {
+				...node,
+				patternElement: {
+					mixinName,
+					allowMarkdownContent: node.attributes.markdown !== undefined
+				}
+			};
+		}
+	}
+];
+
+hexo.extend.filter.register( 'before_post_render', page => {
+	if ( page.projectTheme !== 'gloria' || !page.content ) {
+		return page;
+	}
+
+	const basePath = path.join( hexo.theme_dir, 'layout', 'gloria', '_components' );
+	const result = renderXMLPugComponentsInMarkdown( page.content, {
+		hexo,
+		basePath,
+		patternElements: PATTERN_ELEMENTS,
+		source: page.source,
+		mixinContextVars: {
+			page
+		}
+	} );
+
+	page.content = result;
+
+	return page;
+}, 8 );
+
+hexo.extend.filter.register( 'after_post_render', page => {
+	if ( page.projectTheme !== 'gloria' || !page.content ) {
+		return page;
+	}
+
+	try {
+		page.content = extractReplacementBase64Tag( { page } );
+	} catch ( error ) {
+		console.error( error );
+		throw error;
+	}
+
+	return page;
+} );