_navigation_markup() │ WP 4.1.0

Wraps the provided navigation/pagination links in an HTML template.

Used for the standard output of navigation/pagination links in the functions: the_posts_pagination() and the_posts_navigation().

This function has a useful hook navigation_markup_template, which can be used to change the output template of the block (see example).

Internal function — this function is designed to be used by the kernel itself. It is not recommended to use this function in your code.

Used By: get_the_comments_pagination(), get_the_comments_navigation(), get_the_posts_pagination(), get_the_posts_navigation()
Hooks from the function

Returns

String. HTML template of the navigation block.

Usage

_navigation_markup( $links, $class, $screen_reader_text );
$links(string) (required)
Navigation links.
$class(string)
Additional classes to the main block <nav>. Classes will be added to the existing class navigation.
Default: 'posts-navigation'
$screen_reader_text(string)
Name of the navigation block when read by screen readers (for robots reading code).
Default: __( 'Posts navigation' )

Examples

0

#1 Get a navigation HTML

Let's say we got the navigation links with paginate_links() and now we need to output these links in a standard pagination format:

// get pagination links
$links = paginate_links( $args );

if ( $links ) {
	echo _navigation_markup( $links, 'pagination', 'My cool navigation' );
}
0

#2 Changing the navigation/pagination html template

Suppose we want to change the HTML output in functions: the_posts_pagination(), the_posts_navigation(), we need to remove the H2 heading.

To do this, use the hook: navigation_markup_template:

add_filter( 'navigation_markup_template', 'my_navigation_template', 10, 2 );

function my_navigation_template( $template, $class ){
	/*
	Type of basic template:
	<nav class="navigation %1$s" role="navigation">
		<h2 class="screen-reader-text">%2$s</h2>
		<div class="nav-links">%3$s</div>
	</nav>
	*/

	return '
	<nav class="navigation %1$s" role="navigation">
		<div class="nav-links">%3$s</div>
	</nav>    
	';
}

Changelog

Since 4.1.0 Introduced.
Since 5.3.0 Added the aria_label parameter.

_navigation_markup() code WP 7.0

wp-includes/link-template.php 
function _navigation_markup( $links, $css_class = 'posts-navigation', $screen_reader_text = '', $aria_label = '' ) {
	if ( empty( $screen_reader_text ) ) {
		$screen_reader_text = /* translators: Hidden accessibility text. */ __( 'Posts navigation' );
	}
	if ( empty( $aria_label ) ) {
		$aria_label = $screen_reader_text;
	}

	$template = '
	<nav class="navigation %1$s" aria-label="%4$s">
		<h2 class="screen-reader-text">%2$s</h2>
		<div class="nav-links">%3$s</div>
	</nav>';

	/**
	 * Filters the navigation markup template.
	 *
	 * Note: The filtered template HTML must contain specifiers for the navigation
	 * class (%1$s), the screen-reader-text value (%2$s), placement of the navigation
	 * links (%3$s), and ARIA label text if screen-reader-text does not fit that (%4$s):
	 *
	 *     <nav class="navigation %1$s" aria-label="%4$s">
	 *         <h2 class="screen-reader-text">%2$s</h2>
	 *         <div class="nav-links">%3$s</div>
	 *     </nav>
	 *
	 * @since 4.4.0
	 *
	 * @param string $template  The default template.
	 * @param string $css_class The class passed by the calling function.
	 */
	$template = apply_filters( 'navigation_markup_template', $template, $css_class );

	return sprintf( $template, sanitize_html_class( $css_class ), esc_html( $screen_reader_text ), $links, esc_attr( $aria_label ) );
}

Navigation pagination