tools/docs/gen-block-lib-list.js - trunk - githubmirror/gutenberg

tools/docs/gen-block-lib-list.js
218 строк5 KB
Marco Ciampini
ESLint: Replace strict config with bulk suppressions (#81248)
07 авг 2026, 14:34
07 авг 2026, 14:347f43eaf
/**
 * Generates core block documentation using block.json files.
 * Reads from  : packages/block-library/src
 * Publishes to: docs/reference-guides/core-blocks/README.md
 */
const path = require( 'path' );
const fs = require( 'fs' );
const glob = require( 'fast-glob' );
/**
 * Path to root project directory.
 *
 * @type {string}
 */
const ROOT_DIR = path.resolve( __dirname, '../..' );

/**
 * Path to packages directory.
 *
 * @type {string}
 */
const BLOCK_LIBRARY_DIR = path.resolve(
	ROOT_DIR,
	'packages/block-library/src'
);

/**
 * Path to docs file.
 *
 * @type {string}
 */
const BLOCK_LIBRARY_DOCS_FILE = path.resolve(
	ROOT_DIR,
	'docs/reference-guides/core-blocks/README.md'
);

/**
 * Start token for matching string in doc file.
 *
 * @type {string}
 */
const START_TOKEN = '<!-- START TOKEN Autogenerated - DO NOT EDIT -->';

/**
 * Start token for matching string in doc file.
 *
 * @type {string}
 */
const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';

/**
 * Regular expression using tokens for matching in doc file.
 * Note: `.` does not match new lines, so [^] is used.
 *
 * @type {RegExp}
 */
const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );

/**
 * Returns list of keys, filtering out any experimental
 * and wrapping keys with ~~ to strikeout false values.
 *
 * @type {Object} obj
 * @return {string[]} Array of truthy keys
 */
function getTruthyKeys( obj ) {
	if ( ! obj ) {
		return [];
	}

	return Object.keys( obj )
		.filter( ( key ) => ! key.startsWith( '__exp' ) )
		.map( ( key ) => ( obj[ key ] ? key : `~~${ key }~~` ) );
}

/**
 * Process list of object that may contain inner keys.
 * For example: spacing( margin, padding ).
 *
 * @param {Object} obj
 * @return {string[]} Array of keys (inner keys)
 */
function processObjWithInnerKeys( obj ) {
	const rtn = [];

	const kvs = getTruthyKeys( obj );

	kvs.forEach( ( key ) => {
		if ( Array.isArray( obj[ key ] ) ) {
			rtn.push( `${ key } (${ obj[ key ].sort().join( ', ' ) })` );
		} else if ( typeof obj[ key ] === 'object' ) {
			const innerKeys = getTruthyKeys( obj[ key ] );
			if ( innerKeys.length ) {
				rtn.push( `${ key } (${ innerKeys.sort().join( ', ' ) })` );
			} else {
				rtn.push( key );
			}
		} else {
			rtn.push( key );
		}
	} );
	return rtn;
}

/**
 * Augment supports with additional default props.
 *
 * The color support if specified defaults background and text, if
 * not disabled. So adding { color: 'link' } support also brings along
 * background and text.
 *
 * @param {Object} supports - keys supported by block
 * @return {Object} supports augmented with defaults
 */
function augmentSupports( supports ) {
	if ( 'color' in supports ) {
		// If background or text is not specified (true or false)
		// then add it as true.a
		if ( ! ( 'background' in supports.color ) ) {
			supports.color.background = true;
		}
		if ( ! ( 'text' in supports.color ) ) {
			supports.color.text = true;
		}
	}
	return supports;
}

/**
 * Reads block.json file and returns markdown formatted entry.
 *
 * @param {string} filename
 *
 * @return {string} markdown
 */
function readBlockJSON( filename ) {
	const blockjson = require( filename );
	const {
		name,
		category,
		supports,
		attributes,
		parent,
		ancestor,
		__experimental,
		allowedBlocks,
	} = blockjson;
	const blockdir = path.basename( path.dirname( filename ) );
	const blockDetailUrl = `https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-${ category }/core-block-${ blockdir }/`;
	const blockInfoList = [ `-	**Name:** [${ name }](${ blockDetailUrl })` ];

	if ( __experimental ) {
		blockInfoList.push( `-	**Experimental:** ${ __experimental }` );
	}
	if ( category?.length > 0 ) {
		blockInfoList.push(
			`-	**Category:** [${ category }](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-${ category }/)`
		);
	}
	if ( parent?.length > 0 ) {
		blockInfoList.push( `-	**Parent:** ${ parent.join( ', ' ) }` );
	}
	if ( ancestor?.length > 0 ) {
		blockInfoList.push( `-	**Ancestor:** ${ ancestor.join( ', ' ) }` );
	}
	if ( allowedBlocks?.length > 0 ) {
		blockInfoList.push(
			`-	**Allowed Blocks:** ${ allowedBlocks.join( ', ' ) }`
		);
	}
	if ( supports ) {
		blockInfoList.push(
			`-	**Supports:** ${ processObjWithInnerKeys(
				augmentSupports( supports )
			)
				.sort()
				.join( ', ' ) }`
		);
	}
	const truthyAttributes = getTruthyKeys( attributes );
	if ( truthyAttributes.length ) {
		blockInfoList.push(
			`-	**Attributes:** ${ truthyAttributes.sort().join( ', ' ) }`
		);
	}

	return `
## ${ blockjson.title }

${ blockjson.description }

${ blockInfoList.join( '\n' ) }
`;
}

// Generate block docs.
// Note: The replace() is to translate Windows back to Unix for fast-glob.
const files = glob.sync(
	path.join( BLOCK_LIBRARY_DIR, '*', 'block.json' ).replace( /\\/g, '/' )
);

let autogen = '';

files.forEach( ( file ) => {
	const markup = readBlockJSON( file );
	autogen += markup;
} );

let docsContent = fs.readFileSync( BLOCK_LIBRARY_DOCS_FILE, {
	encoding: 'utf8',
	flag: 'r',
} );

// Add delimiters back.
autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN;
docsContent = docsContent.replace( TOKEN_PATTERN, autogen );

// write back out
fs.writeFileSync( BLOCK_LIBRARY_DOCS_FILE, docsContent, { encoding: 'utf8' } );