the_excerpt()

Display the post excerpt.

Contents

Description Description

Source 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() );
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
0.71 Introduced.

Top ↑

More Information 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.

Top ↑

Comparison with the <!–more–> quicktag 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.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/post-template.php: get_the_excerpt()

Retrieves the post excerpt.
wp-includes/post-template.php: the_excerpt

Filters the displayed post excerpt.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 18You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Control Excerpt Length using Filters
    By default, excerpt length is set to 55 words. To change excerpt length to 20 words using the excerpt_length filter,
    add the following code to the functions.php</code file in your theme:

    /**
 * Filter the except length to 20 words.
 *
 * @param int $length Excerpt length.
 * @return int (Maybe) modified excerpt length.
 */
function wpdocs_custom_excerpt_length( $length ) {
	return 20;
}
add_filter( 'excerpt_length', 'wpdocs_custom_excerpt_length', 999 );

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Make the “read more” string link to the post:
    Place this in a theme’s functions.php to make the “read more” link to the post

    /**
 * Filter the "read more" excerpt string link to the post.
 *
 * @param string $more "Read more" excerpt string.
 * @return string (Maybe) modified "read more" excerpt string.
 */
function wpdocs_excerpt_more( $more ) {
	if ( ! is_single() ) {
		$more = sprintf( '<a class="read-more" href="%1$s">%2$s</a>',
			get_permalink( get_the_ID() ),
			__( 'Read More', 'textdomain' )
		);
	}

	return $more;
}
add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );

    Expand full source codeCollapse full source code

    Note: This link will not appear on a new line. To achieve this, modify the CSS for the .read-more class.

  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Modify the [...] string using filters
    For versions 2.9 and higher of WordPress

    By default, the excerpt “read more” string at the end is set to ‘[…]’. To change the excerpt “read more” string using the excerpt_more filter add the following code to the functions.php file in your theme:

    /**
 * Filter the excerpt "read more" string.
 *
 * @param string $more "Read more" excerpt string.
 * @return string (Maybe) modified "read more" excerpt string.
 */
function wpdocs_excerpt_more( $more ) {
	return '[.....]';
}
add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Use with Conditional Tags
    Replaces the_content() tag with the_excerpt() when on archive or category pages.

    Both the examples below work for versions 1.5 and above.

    <?php if ( is_category() || is_archive() ) {
	the_excerpt();
} else {
	the_content();
} ?>

    This example implies that there is only one template file being used for both categories and archives, e.g. simply archive.php.
    But also that the template shows even other things, so this could simply be index.php.

  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by ekodek —

    Simple function that changes the output of the “[…..]” text:

    function wpdocs_excerpt_more( $more ) {
    return '<a href="'.get_the_permalink().'" rel="nofollow">Read More...</a>';
}
add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );

    You can change the CSS of “my-class” , to everything you want….like a button or whatever.

  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by ghoul —

    The safest way to use this filter is checking for is_admin too as it may alter in the admin area like the following:

    /**
 * Filter the excerpt "read more" string.
 *
 * @param string $more "Read more" excerpt string.
 * @return string (Maybe) modified "read more" excerpt string.
 */
function wpdocs_excerpt_more( $more ) {
	if ( is_admin() ) {
		return $more;
	}
    return '[.....]';
}
add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );
  8. Skip to note 8 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Default Usage
    Displays the post excerpt. Used in templates that provide a form of index, ie. for home, category, tag, archive pages. Not used for single post views. Not meaningful for static pages.

    Used as a replacement for the_content() to force excerpts to show within The Loop.

    <?php the_excerpt(); ?>
  9. Skip to note 9 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Jonm511 —

    Classic Editor: Add a word counter to the bottom of the ‘Excerpt’ field

    This will add a word counter under the ‘Excerpt’ field when creating a new post. Helpful if you would like to limit how long your manually entered excerpt is.

    Add this into your functions.php file:

    /**
 * Use jQuery to add a word counter to the excerpt box
 *
 * Should attach to all post screens and indicate the number of words just below the #excerpt textarea
 */
function gv_excerpt_word_count_js() {
      echo '
     <script>jQuery(document).ready(function(){
jQuery("#postexcerpt #excerpt").after("Word Count: <strong><span id=\'excerpt-word-count\'></span></strong>");
     jQuery("#excerpt-word-count").html(jQuery("#excerpt").val().split(/\S+\b[\s,\.\'-:;]*/).length - 1);
     jQuery("#excerpt").keyup( function() {
     jQuery("#excerpt-word-count").html(jQuery("#excerpt").val().split(/\S+\b[\s,\.\'-:;]*/).length - 1);
   });
});</script>
    ';
}
add_action( 'admin_head-post.php', 'gv_excerpt_word_count_js');
add_action( 'admin_head-post-new.php', 'gv_excerpt_word_count_js');

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.