Skip to content

Conversation

@harshbhonsle
Copy link
Contributor

What?

Closes #72876

Adds support for paginated post content (split using <!--nextpage--> or the Page Break block) in the Breadcrumbs block.


Why?

Currently, the Breadcrumbs block does not indicate the current page when viewing paginated post content.
This enhancement adds a clear “Page X” breadcrumb, improving navigation clarity for long-form posts.

Example:

  • Page 1 → Home › Post Title
  • Page 2 → Home › Post Title / Page 2
  • Page 3 → Home › Post Title / Page 3

This aligns the Breadcrumbs block’s behavior with archive pagination.


How?

  • Reused the existing helper function block_core_breadcrumbs_maybe_add_paged() that already handles archive pagination.
  • Added a call to this helper after the current post title in the single post breadcrumb generation logic.
  • The function now detects both:
    • Archive pagination (paged query var)
    • Paginated post content (page query var)

Testing Instructions

  1. Create or edit a post and insert multiple Page Break blocks (<!--nextpage-->).
  2. Publish and view the post.
  3. Visit:
    • /my-post/ → should show Home / Post Title
    • /my-post/2/ → should show Home / Post Title / Page 2
    • /my-post/3/ → should show Home / Post Title / Page 3
  4. Confirm breadcrumbs update accordingly.

Screenshots or Screencast

Screenshots

Before After
Breadcrumb does not indicate page number on paginated posts.
Before screenshot
Breadcrumb displays Page X for paginated post views.
After screenshot

@github-actions
Copy link

github-actions bot commented Nov 1, 2025

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: harshbhonsle <[email protected]>
Co-authored-by: ntsekouras <[email protected]>
Co-authored-by: tyxla <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@harshbhonsle harshbhonsle force-pushed the feature/breadcrumbs-paginated-posts branch 3 times, most recently from 2159baf to adaa408 Compare November 1, 2025 18:19
@t-hamano t-hamano added [Block] Breadcrumbs (experimental) Affects the Breadcrumbs Block [Type] Enhancement A suggestion for improvement. labels Nov 3, 2025
@tyxla tyxla requested a review from ntsekouras November 3, 2025 08:37
@harshbhonsle
Copy link
Contributor Author

Thanks for the note, @tyxla. Please let me know once #72873 is merged — I’ll update this PR to align with those changes.

@ntsekouras
Copy link
Contributor

Thanks for the PR @harshbhonsle! #72873 landed, so it would be great to rebase/adjust in order to review 😄

@harshbhonsle
Copy link
Contributor Author

harshbhonsle commented Nov 9, 2025

@ntsekouras @tyxla Quick question before merging: for posts that use <!--nextpage--> pagination, should the breadcrumb display as Home / Post Title / Page X or just Home / Page X? I want to make sure the PR matches the intended behavior
image
image

@ntsekouras
Copy link
Contributor

should the breadcrumb display as Home / Post Title / Page X or just Home / Page X?

The former as it should include the post title. Home / Page X is for paged content in the homepage and is already handled.

@harshbhonsle harshbhonsle force-pushed the feature/breadcrumbs-paginated-posts branch from adaa408 to 1c26227 Compare November 11, 2025 06:02
@harshbhonsle
Copy link
Contributor Author

Hi @ntsekouras

I’ve implemented the changes for paginated post support in the Breadcrumbs block. I’m new to contributing, so please let me know if I’ve made any mistakes or if improvements are needed — I’m happy to update them!

Here’s a quick preview of how it looks:

Thanks for taking the time to review my PR.
image

}
// Add current post title (not linked).
$breadcrumb_items[] = block_core_breadcrumbs_create_current_item( block_core_breadcrumbs_get_post_title( $post ), true );
$title = get_the_title( $post );
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the title we have the block_core_breadcrumbs_get_post_title helper function. We shouldn't remove it and see how it fits with the new helper functions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m keeping the current line:

$breadcrumb_items[] = block_core_breadcrumbs_create_current_item(
    block_core_breadcrumbs_get_post_title( $post ),
    true
);

This handles the current post title as before. The new logic I’m adding for paginated posts (Page X) would come after this line so that the breadcrumb shows both the post title and the page number.

Does that approach look good to you?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be easier if you make the changes make reviewing/testing easier.

In general the flow would be to check if is paged and either call block_core_breadcrumbs_create_item or inline the logic there to work for the page query var, as I'm not sure if get_pagenum_link will handle it properly (I think it handles paged query var).

So if is paged -> block_core_breadcrumbs_create_link -> add the Page X item.
If not paged -> you call the existing line in trunk with block_core_breadcrumbs_create_current_item.

Does this help?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I’ve implemented it as suggested: the current post title is always added as a non-linked item, and if the post is paginated, a “Page X” item is appended. Changes have been pushed for review/testing.

* @param array $breadcrumb_items Array of existing breadcrumb items.
* @return array Modified breadcrumb items including "Page X" if needed.
*/
function block_core_breadcrumbs_maybe_add_paged( $breadcrumb_items ) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function has been removed and we have new helper functions since this PR. We should see what we can use in this case, but given the query param is different for pages (page), it might even not need new helper functions and we could possibly inline the logic (last else block in the main render_block_core_breadcrumbs function).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ntsekouras

I’ve implemented the inline logic for paginated post content directly in the else block after the post title — instead of using the removed block_core_breadcrumbs_maybe_add_paged() function.

It checks get_query_var( 'page' ) and adds a “Page X” breadcrumb when greater than 1:

$page_number = max( 1, get_query_var( 'page' ) );
if ( $page_number > 1 ) {
	/* translators: %d: current page number. */
	$breadcrumb_items[] = block_core_breadcrumbs_create_current_item(
		sprintf( esc_html__( 'Page %d', 'gutenberg' ), number_format_i18n( $page_number ) ),
		true
	);
}

Could you please confirm if this approach looks good before I commit and push the changes?

@harshbhonsle harshbhonsle force-pushed the feature/breadcrumbs-paginated-posts branch from e00e804 to 6ce5e3a Compare November 13, 2025 13:16
}
// Add current post title (not linked).
$breadcrumb_items[] = block_core_breadcrumbs_create_current_item( block_core_breadcrumbs_get_post_title( $post ), true );
$breadcrumb_items[] = block_core_breadcrumbs_create_current_item(
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is close, but we should also handle the case where is paged. When it is, we should create a link.

I think the below code would be enough:

$is_paged = (int) get_query_var( 'page' ) > 1;
$title    = block_core_breadcrumbs_get_post_title( $post );

if ( $is_paged ) {
	$breadcrumb_items[] = block_core_breadcrumbs_create_link( get_permalink( $post ), $title, true );
	$breadcrumb_items[] = block_core_breadcrumbs_create_page_number_item( 'page' );
} else {
	$breadcrumb_items[] = block_core_breadcrumbs_create_current_item( $title, true );
}

For that to work though, we'll need another small change in block_core_breadcrumbs_create_page_number_item to pass the query_var like this:

function block_core_breadcrumbs_create_page_number_item( $query_var = 'paged' ) {
	$paged = (int) get_query_var( $query_var );
	return block_core_breadcrumbs_create_current_item(
		/* translators: %s: page number */
		sprintf( __( 'Page %s' ), number_format_i18n( $paged ) )
	);
}

Copy link
Contributor

@ntsekouras ntsekouras left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! Let's get this in.

@ntsekouras ntsekouras changed the title Enhancement: Add support for paginated post content in Breadcrumbs bl… Breadcrumbs: Add support for paginated post content Nov 17, 2025
@ntsekouras ntsekouras enabled auto-merge (squash) November 17, 2025 07:58
@ntsekouras ntsekouras merged commit e424e5d into WordPress:trunk Nov 17, 2025
33 checks passed
@github-actions github-actions bot added this to the Gutenberg 22.2 milestone Nov 17, 2025
@harshbhonsle
Copy link
Contributor Author

Hi @ntsekouras, thank you for your guidance throughout the breadcrumbs pagination PR. Your feedback on the page query var, post title linking, and helper logic was incredibly helpful. As my first Gutenberg feature contribution, your clear explanations — especially around when to inline logic vs. rely on helpers — really helped me understand the Breadcrumbs block internals and workflow. I appreciate you reviewing each iteration. Thanks again for your support and for merging the PR — I’m excited to keep contributing and learning!

@ntsekouras
Copy link
Contributor

Happy to help @harshbhonsle and thank you again for your time and effort to contribute!

@harshbhonsle harshbhonsle deleted the feature/breadcrumbs-paginated-posts branch November 19, 2025 05:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Block] Breadcrumbs (experimental) Affects the Breadcrumbs Block [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Breadcrumbs: Support paginated post content

4 participants