W3cubDocs

/WordPress

the_excerpt()

Display the post excerpt.

Description

Source

File: wp-includes/post-template.php

function the_excerpt() {

	/**
	 * Filters the displayed post excerpt.
	 *
	 * @since 0.71
	 *
	 * @see get_the_excerpt()
	 *
	 * @param string $post_excerpt The post excerpt.
	 */
	echo apply_filters( 'the_excerpt', get_the_excerpt() );
}

Changelog

Version Description
0.71 Introduced.

More Information

Displays the excerpt of the current post after applying several filters to it including auto-p formatting which turns double line-breaks into HTML paragraphs. It uses get_the_excerpt() to first generate a trimmed-down version of the full post content should there not be an explicit excerpt for the post.

The trimmed-down version contains a ‘more’ tag at the end which by default is the […] or “hellip” symbol. A user-supplied excerpt is NOT by default given such a symbol. To add it, you must either modify the raw $post->post_excerpt manually in your template before calling the_excerpt(), add a filter for 'get_the_excerpt' with a priority lower than 10, or add a filter for 'wp_trim_excerpt' (comparing the first and second parameter, because a user-supplied excerpt does not get altered in any way by this function).

See get_the_excerpt() for more details.

An auto-generated excerpt will also have all shortcodes and tags removed. It is trimmed down to a word-boundary and the default length is 55 words. For languages in which words are (or can be) described with single characters (ie. East-Asian languages) the word-boundary is actually the character.

Note: If the current post is an attachment, such as in the attachment.php and image.php template loops, then the attachment caption is displayed. Captions do not include the “[…]” text.

Comparison with the <!–more–> quicktag

Excerpts provide an alternative to the use of the <!--more--> quicktag. Whereas this more tag requires a post author to manually create a ‘split’ in the post contents, which is then used to generate a “read more” link on index pages, the excerpts require, but do not necessarily demand, a post author to supply a ‘teaser’ for the full post contents.

The <!--more--> quicktag requires templates to use the_content() whereas using excerpts requires, and allows, template writers to explicitly choose whether to display full posts (using the_content()) or excerpts (using the_excerpt()).

The choice of whether to display a full post or an excerpt can then be based on factors such as the template used, the type of page, the category of the post, etcetera. In other words, with a <!--more--> quicktag the post author decides what happens, whereas the template writer is in control with excerpts. Moreover, although <!--more--> can be used to create a real split using the $stripteaser parameter, it would be hard and complicated to then differentiate based on characteristics, causing this to become a basically site-wide choice.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/the_excerpt