Template Hierarchy

<?php
/**
 * Adds "single-lp_book-{genre}" candidates, so a theme can style each genre's books.
 *
 * File: wp-content/plugins/lumen-catalog/includes/genre-templates.php
 */

defined( 'ABSPATH' ) || exit;

add_filter( 'single_template_hierarchy', 'lumen_catalog_genre_templates' );

function lumen_catalog_genre_templates( $templates ) {
	$book = get_queried_object();
	if ( ! $book instanceof WP_Post || 'lp_book' !== $book->post_type ) {
		return $templates;
	}

	$genres = get_the_terms( $book, 'lp_genre' );
	if ( ! is_array( $genres ) ) {
		return $templates;
	}

	$extra = array();
	foreach ( $genres as $genre ) {
		$extra[] = 'single-lp_book-' . sanitize_file_name( $genre->slug ) . '.php';
	}

	// Insert the genre templates just before "single-lp_book.php".
	$position = array_search( 'single-lp_book.php', $templates, true );
	array_splice( $templates, false === $position ? 0 : $position, 0, $extra );

	return $templates;
}

lumen /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book-literary-fiction.php single-lp_book.php single.php
  => wp-includes/template-canvas.php
  => block template lumen//single-lp_book-literary-fiction (source: theme)
lumen-classic /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book-literary-fiction.php single-lp_book.php single.php
  => wp-content/themes/lumen-classic/single-lp_book-literary-fiction.php

<?php
/**
 * Default book templates for themes that do not ship their own.
 *
 * File: wp-content/plugins/lumen-catalog/includes/templates.php
 */

defined( 'ABSPATH' ) || exit;

/*
 * Block themes: register "single-lp_book" in the template registry (WordPress 6.7+).
 * A theme file or a user-edited template with the same slug wins over it.
 */
add_action( 'init', 'lumen_catalog_register_block_templates' );

function lumen_catalog_register_block_templates() {
	if ( ! function_exists( 'register_block_template' ) ) {
		return;
	}

	register_block_template(
		'lumen-catalog//single-lp_book',
		array(
			'title'       => __( 'Single Book', 'lumen-catalog' ),
			'description' => __( 'Displays a single book of the catalogue.', 'lumen-catalog' ),
			'content'     => (string) file_get_contents( dirname( __DIR__ ) . '/templates/single-lp_book.html' ),
		)
	);
}

/*
 * Classic themes: use the plugin's PHP template when the theme has no single-lp_book.php.
 */
add_filter( 'template_include', 'lumen_catalog_template_include' );

function lumen_catalog_template_include( $template ) {
	if ( wp_is_block_theme() || ! is_singular( 'lp_book' ) ) {
		return $template;
	}

	if ( '' !== locate_template( array( 'single-lp_book.php' ) ) ) {
		return $template;
	}

	return dirname( __DIR__ ) . '/templates/single-lp_book.php';
}

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:post-title {"level":1} /-->
	<!-- wp:post-terms {"term":"lp_genre"} /-->
	<!-- wp:post-featured-image /-->
	<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

twentytwentyfive /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book.php single.php
  => wp-includes/template-canvas.php
  => block template twentytwentyfive//single-lp_book (source: plugin)
lumen /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book.php single.php
  => wp-includes/template-canvas.php
  => block template lumen//single-lp_book (source: custom)
lumen-classic /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book.php single.php
  => wp-content/plugins/lumen-catalog/templates/single-lp_book.php

# compose.yaml
name: lumen-th
x-wp-db: &wp-db
  WORDPRESS_DB_HOST: db
  WORDPRESS_DB_USER: wordpress
  WORDPRESS_DB_PASSWORD: ${WP_DB_PASSWORD:?set WP_DB_PASSWORD}
  WORDPRESS_DB_NAME: wordpress
x-wp-code: &wp-code
  - wp:/var/www/html
  - ./site/mu-plugins:/var/www/html/wp-content/mu-plugins:ro
  - ./site/plugins/lumen-catalog:/var/www/html/wp-content/plugins/lumen-catalog:ro
  - ./site/themes/lumen:/var/www/html/wp-content/themes/lumen:ro
  - ./site/themes/lumen-classic:/var/www/html/wp-content/themes/lumen-classic:ro
services:
  db:
    image: mariadb:11.8
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${WP_DB_PASSWORD:?set WP_DB_PASSWORD}
      MARIADB_RANDOM_ROOT_PASSWORD: "1"
    tmpfs: [/var/lib/mysql]
  web:
    image: wordpress:7.1.3-php8.4-apache
    depends_on: [db]
    environment: *wp-db
    networks:
      default:
        aliases: [lumenpress.test]
    volumes: *wp-code
  cli:
    image: wordpress:cli-2.12.0-php8.4
    depends_on: [web]
    user: "33:33"
    environment:
      <<: *wp-db
      WP_ADMIN_PASSWORD: ${WP_ADMIN_PASSWORD:?set WP_ADMIN_PASSWORD}
    volumes: *wp-code
    entrypoint: ["sleep", "infinity"]
volumes:
  wp: {}

export WP_DB_PASSWORD='<a-local-db-password>' WP_ADMIN_PASSWORD='<a-local-admin-password>'
docker compose up -d
# The web container copies WordPress into the volume and writes wp-config.php on first start.
until docker compose exec -T cli wp db check >/dev/null 2>&1; do sleep 2; done
docker compose exec -T cli sh <<'EOF'
set -e
wp core install --url=http://lumenpress.test --title="Lumen Press" --admin_user=admin \
  --admin_email=admin@lumenpress.test --admin_password="$WP_ADMIN_PASSWORD" --skip-email
wp config set WP_DEBUG true --raw
wp plugin activate lumen-catalog
wp rewrite structure '/%year%/%monthnum%/%postname%/'
wp user create maria.editor maria@lumenpress.test --role=editor --user_pass="$WP_ADMIN_PASSWORD"
wp user create tom.author tom@lumenpress.test --role=author --user_pass="$WP_ADMIN_PASSWORD"
HOME_ID=$(wp post create --post_type=page --post_status=publish --post_title=Home --porcelain)
NEWS_ID=$(wp post create --post_type=page --post_status=publish --post_title=News --porcelain)
wp post create --post_type=page --post_status=publish --post_title=About
wp option update show_on_front page
wp option update page_on_front "$HOME_ID"
wp option update page_for_posts "$NEWS_ID"
wp post update 1 --post_author=3 --post_title='Autumn catalogue announced' --post_name=autumn-catalogue \
  --post_date='2026-10-01 10:00:00'
wp term create lp_genre 'Literary Fiction' --slug=literary-fiction
BOOK=$(wp post create --post_type=lp_book --post_status=publish --post_title='The Glass Orchard' \
  --post_name=the-glass-orchard --porcelain)
wp post term set "$BOOK" lp_genre literary-fiction
wp post create --post_type=attachment --post_mime_type=image/jpeg --post_status=inherit \
  --post_parent="$BOOK" --post_title='Glass Orchard cover' --post_name=glass-orchard-cover
wp option update wp_attachment_pages_enabled 1
wp rewrite flush
EOF

for theme in lumen lumen-classic; do
  docker compose exec -T cli wp theme activate "$theme"
  docker compose exec -T cli sh -c 'for path in / /news/ /2026/10/autumn-catalogue/ /about/ /books/ \
      /books/the-glass-orchard/ /genre/literary-fiction/ /author/tom-author/ /2026/10/ "/?s=orchard" \
      /no-such-page/ /books/the-glass-orchard/glass-orchard-cover/ /books/the-glass-orchard/embed/; do
    curl -s -o /dev/null -w "%{http_code} $path\n" "http://lumenpress.test$path"
  done'
done
docker compose exec -T cli cat wp-content/uploads/lumen-template-debug.log

lumen /
  frontpage     front-page.php
  page          page-home.php page-5.php page.php
  => wp-includes/template-canvas.php
  => block template lumen//page (source: theme)
lumen /news/
  home          home.php index.php
  => wp-includes/template-canvas.php
  => block template lumen//home (source: theme)
lumen /2026/10/autumn-catalogue/
  single        single-post-autumn-catalogue.php single-post.php single.php
  => wp-includes/template-canvas.php
  => block template lumen//single (source: theme)
lumen /about/
  page          page-about.php page-7.php page.php
  => wp-includes/template-canvas.php
  => block template lumen//page (source: theme)
lumen /books/
  archive       archive-lp_book.php archive.php
  => wp-includes/template-canvas.php
  => block template lumen//archive-lp_book (source: theme)
lumen /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book.php single.php
  => wp-includes/template-canvas.php
  => block template lumen//single-lp_book (source: theme)
lumen /genre/literary-fiction/
  taxonomy      taxonomy-lp_genre-literary-fiction.php taxonomy-lp_genre-2.php taxonomy-lp_genre.php taxonomy.php
  => wp-includes/template-canvas.php
  => block template lumen//taxonomy-lp_genre (source: theme)
lumen /author/tom-author/
  author        author-tom-author.php author-3.php author.php
  archive       archive.php
  => wp-includes/template-canvas.php
  => block template lumen//archive (source: theme)
lumen /2026/10/
  date          date.php
  archive       archive.php
  => wp-includes/template-canvas.php
  => block template lumen//archive (source: theme)
lumen /?s=orchard
  search        search.php
  => wp-includes/template-canvas.php
  => block template lumen//search (source: theme)
lumen /no-such-page/
  404           404.php
  => wp-includes/template-canvas.php
  => block template lumen//404 (source: theme)
lumen /books/the-glass-orchard/glass-orchard-cover/
  attachment    image-jpeg.php jpeg.php image.php attachment.php
  single        single-attachment-glass-orchard-cover.php single-attachment.php single.php
  => wp-includes/template-canvas.php
  => block template lumen//single (source: theme)
lumen /books/the-glass-orchard/embed/
  embed         embed-lp_book.php embed.php
  => wp-includes/theme-compat/embed.php

lumen-classic /
  frontpage     front-page.php
  page          page-home.php page-5.php page.php
  => wp-content/themes/lumen-classic/page.php
lumen-classic /books/the-glass-orchard/
  single        single-lp_book-the-glass-orchard.php single-lp_book.php single.php
  => wp-content/themes/lumen-classic/single-lp_book.php

lumen-classic /2026/10/
  date          date.php
  archive       archive.php
  index         index.php
  => wp-content/themes/lumen-classic/index.php
lumen /2026/10/
  date          date.php
  archive       archive.php
  index         index.php
  => wp-includes/template-canvas.php
  => block template lumen//index (source: theme)