The WordPress excerpts system works properly, but it uses lots of functions and it’s hard to know which one does what.
The WordPress post excerpts system works great, but it also feels more complicated than it needs to be.
The main issue (as is often true in WordPress) is that the WordPress excerpts system uses a lot of functions with near-identical-sounding names. This makes it really hard to know what does what, and which function can help us do the specific thing we’re trying to do with our own WordPress post excerpts.
Taking a “How-To” Approach to WordPress Post Excerpts
So rather than try to dive into every one of the functions involved in creating WordPress post excerpts themselves, this article takes a “how-to” approach to WordPress excerpts, based on what I believe are common goals for people using or modifying their post excerpts.
We’ll cover six needs:
- How to change the length (in words) of WordPress excerpts—the ones used by
the_excerpt()andget_the_excerpt()—using theexcerpt_lengthfilter. - How to change the […] or “Read More” text of WordPress excerpts using the
excerpt_morefilter. - How to change the text of a post excerpt using the
get_the_excerptfilter. - How to create post excerpts that are exactly one paragraph long using the
wp_trim_excerptfilter. - How to create post excerpts of a specific character length (rather than a word length) with the
wp_trim_excerptfilter. - How to get an excerpt of any length from any string using the
wp_trim_words()function.
By the way, if you happen to be wanting simply to create custom post excerpt text for a specific post, the way to do that is quite easy and doesn’t involve code. View our Quick Guide on the topic for details.
What You’ll Need to Understand These Examples
These examples are all in WordPress’s main programming language, PHP. They make extensive use of WordPress’s hooks system, especially WordPress filters. If you need to understand either topic, please read our introduction to it.
And if you feel (in these code demos or in general) a strong need to better understand WordPress in general, then boy have we got the resource for you:
The Best Way to Learn WordPress Development
Get Up and Running Today
Up and Running is our complete “learn WordPress development” course. Now in its updated and expanded Third Edition, it’s helped hundreds of happy buyers learn WordPress development the fast, smart, and thorough way.
Here’s what they have to say:
“I think anyone interested in learning WordPress development NEEDS this course. Watching the videos was like a bunch of lights being turned on.” -Jason, WordPress developer
“Other courses I’ve tried nearly always lack clear explanations for why WordPress does things a certain way, or how things work together. Up and Running does all of this, and everything is explained clearly and in easy-to-understand language.” -Caroline, WordPress freelancer
Demo of How WordPress’s Default Excerpts Work With the_excerpt()
Throughout this article, we’ll be demoing different changes to WordPress excerpts using the same text. Here is the full text, called using the_content() inside the Loop:
And here is the default excerpt, called by using the_excerpt() in place of the_content():
As you can see, the default the_excerpt() functionality pulls the first 55 words of a post’s content, and then follows it with [...]. You’ll see how this behavior changes with each of our demos. Onward to the demos themselves!
1. How to Change the Length of Your WordPress Excerpts with the excerpt_length Filter
function wpshout_longer_excerpts( $length ) {
// Don't change anything inside /wp-admin/
if ( is_admin() ) {
return $length;
}
// Set excerpt length to 140 words
return 140;
}
// "999" priority makes this run last of all the functions hooked to this filter, meaning it overrides them
add_filter( 'excerpt_length', 'wpshout_longer_excerpts', 999 );Used in a WordPress template file like index.php or page.php, before the call to the_excerpt(), the code above gives this result:
You can also use the code above in functions.php (or a plugin) to change calls to the_excerpt() across your entire site.
Notes on excerpt_length
This is a simple filter function that gives you a length in words, and invites you to return back your own custom length—in this case, 140 words.
2. How to Change the “Read More” Text of Your WordPress Excerpts with the excerpt_more Filter
function wpshout_change_and_link_excerpt( $more ) {
if ( is_admin() ) {
return $more;
}
// Change text, make it link, and return change
return '… <a href="' . get_the_permalink() . '">More doggerel »</a>';
}
add_filter( 'excerpt_more', 'wpshout_change_and_link_excerpt', 999 );Used in a WordPress template file like index.php or page.php, before the call to the_excerpt(), the code above gives this result:
You can also use the code above in functions.php (or a plugin) to change calls to the_excerpt() across your entire site.
Notes on excerpt_more
This is a filter function that gives you a “Read More” string (the default is [...]), and invites you to return back your own custom string.
In the example above, we generated the post permalink using get_the_permalink(), and wrapped the text in an <a> tag linking to it. That, and anything else, is possible within excerpt_more, as long as what you’re returning back is a string.
3. How to Change the Text of a Post Excerpt with the get_the_excerpt Filter
function wpshout_make_excerpt_text_interesting( $excerpt ) {
if ( is_admin() ) {
return $excerpt;
}
$excerpt = str_replace( array('rain', 'wind', 'scanty flame of the lamps'), 'DINOSAURS', $excerpt );
return $excerpt;
}
add_filter( 'get_the_excerpt', 'wpshout_make_excerpt_text_interesting', 999 );Used in a WordPress template file like index.php or page.php, before the call to the_excerpt(), the code above gives this result:
You can also use the code above in functions.php (or a plugin) to change calls to the_excerpt() across your entire site.
Notes on the get_the_excerpt Filter
Note that we’re using the get_the_excerpt filter, which is different from the function get_the_excerpt(). The relationship between the two is as follows: when get_the_excerpt() is called, one thing it does is filter itself using the get_the_excerpt filter. And since the main behavior of the_excerpt() is simply to call get_the_excerpt() and echo the result, calls to the_excerpt() will always pass through the get_the_excerpt filter.
The filter itself passes you a string that is the full excerpt content that the_excerpt() would print onto the page. You can then return back your own custom string. In the example above, we used PHP’s str_replace() to change the text in specific ways, and then returned back the changed result.
4. How to Create One-Paragraph Excerpts with the wp_trim_excerpt Filter
function wpshout_excerpt( $text ) {
if( is_admin() ) {
return $text;
}
// Fetch the content with filters applied to get <p> tags
$content = apply_filters( 'the_content', get_the_content() );
// Stop after the first </p> tag
$text = substr( $content, 0, strpos( $content, '</p>' ) + 4 );
return $text;
}
// Leave priority at default of 10 to allow further filtering
add_filter( 'wp_trim_excerpt', 'wpshout_excerpt', 10, 1 );Used in a WordPress template file like index.php or page.php, before the call to the_excerpt(), the code above gives this result:
You can also use the code above in functions.php (or a plugin) to change calls to the_excerpt() across your entire site.
Notes on the wp_trim_excerpt Filter
The function wp_trim_excerpt() is the main function that actually generates an excerpt from WordPress post content (by shortening it to 55 words and adding “[…]”). Before it finishes, it calls the wp_trim_excerpt filter to let you filter the results.
We’re using the wp_trim_excerpt filter to generate and return back our completely own excerpt behavior. For us, we run get_the_content() with the the_content filter applied. One of the things this does is call wpautop() on the post content, wrapping things in <p> tags.
Now that we have our content, wrapped in <p> tags, we cut that string down until just after the first </p> tag to close the first paragraph. And that’s how we get the first paragraph from our text as an excerpt.
5. How to Create Excerpts of a Specific Character Length (Rather than Word Length) with the wp_trim_excerpt Filter
function wpshout_twitter_length_excerpt( $text ) {
if( is_admin() ) {
return $text;
}
// Fetch the post content directly
$text = get_the_content();
// Clear out shortcodes
$text = strip_shortcodes( $text );
// Get the first 140 characteres
$text = substr( $text, 0, 140 );
// Add a read more tag
$text .= '…';
return $text;
}
// Leave priority at default of 10 to allow further filtering
add_filter( 'wp_trim_excerpt', 'wpshout_twitter_length_excerpt', 10, 1 );Used in a WordPress template file like index.php or page.php, before the call to the_excerpt(), the code above gives this result:
You can also use the code above in functions.php (or a plugin) to change calls to the_excerpt() across your entire site.
Notes on the wp_trim_excerpt Filter
The function wp_trim_excerpt() is the main function that actually generates an excerpt from WordPress post content (by shortening it to 55 words and adding “[…]”). Before it finishes, it calls the wp_trim_excerpt filter to let you filter the results.
We’re using the wp_trim_excerpt filter to generate and return back our completely own excerpt behavior. For us, we run get_the_content() to get the post content afresh. We then strip out whatever shortcodes may be in the post, use the substr() function to take the first 140 characters, add an &hellip (“…”) tag to the end, and return back to the end.
6. How to Use wp_trim_words() to Get a WordPress Excerpt of Any Length from Arbitrary Text
// We're creating $read_more, a string that we'll place after the excerpt
$read_more = '… <a class="read-more-link" href="' . get_the_permalink() . '">Read Full Article</a>';
// wpautop() auto-wraps text in paragraphs
echo wpautop(
// wp_trim_words() gets the first X words from a text string
wp_trim_words(
get_the_content(), // We'll use the post's content as our text string
55, // We want the first 55 words
$read_more // This is what comes after the first 55 words
)
);Used instead of the_excerpt(), the above code produces this result:
Notes on the wp_trim_words() Function
wp_trim_words() is the most basic function of the ones we’ve looked at. It’s the one whose actual behavior is to take a string—any string—and return the first however many words from it, with a “Read More” string stuck onto the end.
You can call this function directly to generate your own WordPress excerpts, completely outside of WordPress’s the_excerpts() system. Although the example above still uses the post content (pulled in using get_the_content()), you can use wp_trim_words() to generate excerpts from anything—post titles, meta descriptions, author bios, you name it—because wp_trim_words() can accept any text string as its first argument.
This function is also nice for generating your own completely custom excerpts (even ones that use the_content()) outside of the existing system of filters that exist to change the_excerpt().
So you might want to use it, for example, if you have a single post or post type whose excerpts you want to work completely differently from every other one on the site, and you don’t want to worry about changing all the existing excerpt rules in your themes and plugins.
Further Discussion
Where using WordPress post excerpts often gets complicated is: the whole system overlaps, and so if you’re coming in on an existing project it’s often very hard to tell what’s already been done to the default WordPress filter functionality by the time you get to it.
I mention this problem not to “solve” it—it’s an issue with event-driven systems like WordPress in general—but to clue you in as to the type of issue to look for if your excerpts simply aren’t behaving as you expect. Chances are, somebody’s changing them already, in a theme, plugins, or both. The functions.php in your theme and child theme are good first guesses, so search them for the string “excerpt” to see what might be going on.
In Conclus […]
Now you’ve got a much better sense how to work with WordPress post excerpts. Cheers, and if this article helped you, then don’t forget to Read More »
Well Done!
Thanks