Add Handbook plugin

Some experiments need to edit this as well, so it should be tracked in the repo.

composer.json

@@ -51,16 +51,6 @@
 						"reference": "trunk/wordpress.org/public_html/wp-content/mu-plugins/pub/"
 					}
 				},
-				{
-					"name": "wordpress-meta/handbook",
-					"type": "wordpress-plugin",
-					"version": "1",
-					"source": {
-						"type": "svn",
-						"url": "https://meta.svn.wordpress.org/sites/",
-						"reference": "trunk/wordpress.org/public_html/wp-content/plugins/handbook/"
-					}
-				},
 				{
 					"name": "wordpress-meta/wporg-markdown",
 					"type": "wordpress-plugin",
@@ -96,7 +86,6 @@
 		"wpackagist-plugin/jetpack": "*",
 		"wordpress-meta/wporg": "1",
 		"wordpress-meta/pub": "1",
-		"wordpress-meta/handbook": "1",
 		"wordpress-meta/wporg-markdown": "1",
 		"wordpress/phpdoc-parser": "dev-master",
 		"wporg/wporg-repo-tools": "dev-trunk",

source/wp-content/plugins/handbook/.wp-env.json

@@ -0,0 +1,4 @@
+{
+	"core": "WordPress/WordPress#master",
+	"plugins": [ "." ]
+}

source/wp-content/plugins/handbook/functionality-for-pages.php

@@ -0,0 +1,19 @@
+<?php
+/**
+ * Plugin Name: Handbook Functionality for Pages
+ * Description: Adds handbook-like table of contents to all Pages for a site. Covers Table of Contents and the "watch this page" widget.
+ * Author: Nacin
+ */
+
+require_once dirname( __FILE__ ) . '/inc/table-of-contents.php';
+require_once dirname( __FILE__ ) . '/inc/email-post-changes.php';
+
+new WPorg_Handbook_TOC( array( 'page' ) );
+
+add_filter( 'wporg_email_changes_for_post_types', 'wporg_email_changes_for_pages' );
+function wporg_email_changes_for_pages( $post_types ) {
+	if ( ! in_array( 'page', $post_types ) )
+		$post_types[] = 'page';
+	return $post_types;
+}
+

source/wp-content/plugins/handbook/handbook.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * Plugin Name: Handbook
+ * Description: Features for a handbook, complete with glossary and table of contents
+ * Version:     2.0
+ * Author:      WordPress.org
+ * Author URI:  https://wordpress.org/
+ * License:     GPLv2 or later
+ * Text Domain: wporg
+ */
+
+const WPORG_HANDBOOK_PLUGIN_FILE = __FILE__;
+
+require_once __DIR__ . '/inc/init.php';
+require_once __DIR__ . '/inc/handbook.php';
+require_once __DIR__ . '/inc/admin-notices.php';
+require_once __DIR__ . '/inc/callout-boxes.php';
+require_once __DIR__ . '/inc/glossary.php';
+require_once __DIR__ . '/inc/navigation.php';
+require_once __DIR__ . '/inc/breadcrumbs.php';
+require_once __DIR__ . '/inc/table-of-contents.php';
+require_once __DIR__ . '/inc/template-tags.php';
+require_once __DIR__ . '/inc/email-post-changes.php';
+require_once __DIR__ . '/inc/walker.php';
+require_once __DIR__ . '/inc/watchlist.php';
+require_once __DIR__ . '/inc/blocks.php';
+
+add_action( 'plugins_loaded', function () {
+	if ( class_exists( 'WordPressdotorg\\Markdown\\Importer' ) ) {
+		require_once __DIR__ . '/inc/importer.php';
+	}
+}, 1 );

source/wp-content/plugins/handbook/inc/admin-notices.php

@@ -0,0 +1,163 @@
+<?php
+/**
+ * Class to output helpful admin notices.
+ *
+ * @package handbook
+ */
+
+class WPorg_Handbook_Admin_Notices {
+
+	/**
+	 * Initializes functionality.
+	 *
+	 * @access public
+	 */
+	public static function init() {
+		add_action( 'admin_notices', [ __CLASS__, 'show_new_handbook_message' ] );
+		add_action( 'admin_notices', [ __CLASS__, 'show_imported_handbook_notice' ] );
+		add_action( 'admin_notices', [ __CLASS__, 'show_imported_handbook_config_errors' ] );
+	}
+
+	/**
+	 * Outputs admin notice showing tips for newly created handbook.
+	 *
+	 * @todo Maybe instead of hiding the message once posts are present it should persist as long as no landing page has been created?
+	 *
+	 * @access public
+	 */
+	public static function show_new_handbook_message() {
+		global $wp_query;
+
+		$current_screen = get_current_screen();
+
+		// Only show message in listing of handbook posts when no posts are present yet.
+		if (
+			$current_screen
+		&&
+			'edit' === $current_screen->base
+		&&
+			in_array( $current_screen->post_type, wporg_get_handbook_post_types() )
+		&&
+			0 === $wp_query->post_count
+		&&
+			( empty( $wp_query->query_vars['post_status'] ) || 'publish' === $wp_query->query_vars['post_status'] )
+		) {
+			echo '<div class="notice notice-success"><p>';
+
+			$suggested_slugs = array_unique( [
+				str_replace( '-handbook', '', $current_screen->post_type ),
+				'welcome',
+				$current_screen->post_type,
+				'handbook',
+			] );
+			$suggested_slugs = array_map( function( $x ) { return "<code>{$x}</code>"; }, $suggested_slugs );
+
+			printf(
+				/* translators: 1: example landing page title that includes post type name, 2: comma-separated list of acceptable post slugs */
+				__( '<strong>Welcome to your new handbook!</strong> It is recommended that the first post you create is the landing page for the handbook. You can title it anything you like (suggestions: <code>%1$s</code> or <code>Welcome</code>). However, you must ensure that it has one of the following slugs: %2$s. The slug will ultimately be omitted from the page&#8216;s permalink URL, but will still appear in the permalinks for sub-pages.', 'wporg' ),
+				WPorg_Handbook::get_name( $current_screen->post_type ),
+				implode( ', ', $suggested_slugs )
+			);
+			echo "</p></div>\n";
+		}
+	}
+
+	/**
+	 * Outputs admin notice indicating the handbook is an imported handbook, if applicable.
+	 *
+	 * @access public
+	 */
+	public static function show_imported_handbook_notice() {
+		global $wp_query;
+
+		// Bail if handbook importer is not available.
+		if ( ! class_exists( 'WPorg_Handbook_Importer' ) ) {
+			return;
+		}
+
+		$current_screen = get_current_screen();
+
+		// Only show message in listing of handbook posts when no posts are present yet.
+		if (
+			$current_screen
+		&&
+			'edit' === $current_screen->base
+		&&
+			in_array( $current_screen->post_type, wporg_get_handbook_post_types() )
+		&&
+			WPorg_Handbook_Importer::is_handbook_imported( $current_screen->post_type )
+		) {
+			$handbook_config = WPorg_Handbook_Init::get_handbooks_config( $current_screen->post_type );
+
+			$handbook = WPorg_Handbook_Init::get_handbook( $current_screen->post_type );
+			if ( ! $handbook ) {
+				return;
+			}
+
+			$importer = $handbook->get_importer();
+			$interval = $importer ? $importer->get_cron_interval( false ) : [];
+			$interval_display = ! empty( $interval['display'] ) ? strtolower( $interval['display'] ) : __( 'DISABLED', 'wporg' );
+
+			echo '<div class="notice notice-info"><p>';
+			printf(
+				/* translators: 1: URL to remote manifest. 2: cron interval. */
+				__( '<strong>This is an imported handbook!</strong> This handbook is imported according to a <a href="%1$s">remote manifest</a>. Any local changes will be overwritten during the next import, so make any changes at the remote location. Import interval: <strong>%2$s</strong>.', 'wporg' ),
+				$handbook_config['manifest'],
+				$interval_display
+			);
+			echo "</p></div>\n";
+		}
+	}
+
+	/**
+	 * Outputs admin error notice(s) for any misconfigured imported handbooks.
+	 *
+	 * @access public
+	 */
+	public static function show_imported_handbook_config_errors() {
+		global $wp_query;
+
+		// Bail if handbook importer is not available.
+		if ( ! class_exists( 'WPorg_Handbook_Importer' ) ) {
+			return;
+		}
+
+		$current_screen = get_current_screen();
+
+		// Only show message in listing of handbook posts when no posts are present yet.
+		if (
+			$current_screen
+		&&
+			'edit' === $current_screen->base
+		&&
+			in_array( $current_screen->post_type, wporg_get_handbook_post_types() )
+		&&
+			WPorg_Handbook_Importer::is_handbook_imported( $current_screen->post_type )
+		) {
+			$handbook_config = WPorg_Handbook_Init::get_handbooks_config( $current_screen->post_type );
+
+			$handbook = WPorg_Handbook_Init::get_handbook( $current_screen->post_type );
+			if ( ! $handbook ) {
+				return;
+			}
+
+			$handbook_config = $handbook->get_config();
+			$cron_intervals = wp_get_schedules();
+			$interval_display = $handbook_config[ 'cron_interval' ] ?? '';
+
+			if ( ! empty( $cron_intervals[ $interval_display ] ) ) {
+				return;
+			}
+
+			echo '<div class="notice notice-warning"><p>';
+			printf(
+				/* translators: %s: cron interval. */
+				__( '<strong>Misconfigured cron interval!</strong> This imported handbook has a misconfigured cron interval. The config defines an interval of <strong>%s</strong>, which has not been defined. The fallback import interval shown in a notice above includes the default cron interval currently in use.', 'wporg' ),
+				$interval_display
+			);
+			echo "</p></div>\n";
+		}
+	}
+}
+
+add_action( 'plugins_loaded', [ 'WPorg_Handbook_Admin_Notices', 'init' ] );

source/wp-content/plugins/handbook/inc/blocks.php

@@ -0,0 +1,60 @@
+<?php
+/**
+ * Class providing blocks for the block editor.
+ *
+ * @package handbook
+ */
+
+class WPorg_Handbook_Blocks {
+
+	/**
+	 * Initializes handbook blocks.
+	 */
+	public static function init() {
+		add_action( 'init', array( __CLASS__, 'do_init' ) );
+	}
+
+	/**
+	 * Fires on 'init' action.
+	 *
+	 * @access public
+	 */
+	public static function do_init() {
+		$script_path       = plugin_dir_path( WPORG_HANDBOOK_PLUGIN_FILE ) . 'scripts/blocks.js';
+		$script_asset_path = plugin_dir_path( WPORG_HANDBOOK_PLUGIN_FILE ) . 'scripts/blocks.asset.php';
+		$script_asset      = file_exists( $script_asset_path ) ?
+			require $script_asset_path :
+			[
+				'dependencies' => [],
+				'version'      => filemtime( $script_path ),
+			];
+
+		// TODO: Update after https://github.com/WordPress/gutenberg/issues/14801 is fixed.
+		wp_register_style(
+			'wporg-handbook-blocks',
+			plugins_url( 'scripts/src/blocks/callout/editor.css', __DIR__ ),
+			[],
+			$script_asset['version']
+		);
+
+		wp_register_script(
+			'wporg-handbook-blocks',
+			plugins_url( 'scripts/blocks.js', __DIR__ ),
+			$script_asset['dependencies'],
+			$script_asset['version'],
+			true
+		);
+
+		wp_set_script_translations( 'wporg-handbook-blocks', 'wporg' );
+
+		register_block_type(
+			'wporg/callout',
+			[
+				'editor_style'  => 'wporg-handbook-blocks',
+				'editor_script' => 'wporg-handbook-blocks',
+			]
+		);
+	}
+}
+
+WPorg_Handbook_Blocks::init();