Displaying post excerts in WordPress can be surprisingly confusing. Here's an explanation of the options.
WordPress Default Excerpts
A WP post lets you define the main content, and an optional excerpt. By default, pages do not offer excerpts, but you can change that.
In the theme, theme developers have access to the the_excerpt() template tag. If you have filled in the excerpt box, WP displays your custom excerpt (this is the a great way to write up a custom 'teaser' for long posts).
If you left the excerpt field blank, the the_excerpt() tag does the following:
- strips out all HTML and images
- truncates your post to 55 words
- adds this to the end of the text: "[...]"
Sometimes this is okay, but in general the [...] makes it too ugly to use without customization on most sites.
Note: the [...] text is included inside the last paragraph, without any span or other container around it. If a post has a custom excerpt, then no "more" text is displayed at all afterwards.
Modifying the Excerpt
Fortunately, the excerpt word count and [...] text can be modified with a little code - you can even add a "more" link to the end of the excerpt.
the_excerpt - Changing the Word Count
<?php
function custom_excerpt_length( $length ) {
return 35;
}
add_filter( 'excerpt_length', 'custom_excerpt_length' );
?>
the_excerpt - Replacing [...] with just ...
<?php
function custom_excerpt_more( $excerpt ) {
return str_replace( '[...]', '...', $excerpt );
}
add_filter( 'wp_trim_excerpt', 'custom_excerpt_more' );
?>
the_excerpt - Replacing [...] with a link
<?php
function custom_excerpt($text)
{
return str_replace('[...]', '<a href="'. get_permalink($post->ID) . '">' . '» Continue Reading.' . '</a>', $text);
}
add_filter('the_excerpt', 'custom_excerpt');
?>
WP Note: I hope someday these excerpt settings can be options in the Reading settings panel!
Excerpt Plugins
For even more flexibility, check out the Advanced Excerpt plugin - which can fine tune or disable the HTML filtering, provides custom "more" links, offers counting by word or character, and other options. Or check out Fancy Excerpt, which provides clean "sentence aware" excerpts.
Note: Some of these plugins work by overriding the_excerpt, while others give you a separate function for getting what you want. Read the instructions.
Also Note: if you do use a plugin to allow HTML in your excerpts, make sure your plugin takes care to close any open HTML tags. You don't want to allow a random unclosed <strong> or <a> tag to destroy your website's user experience someday. And if you're truncating the excerpt by character count, make sure the plugin won't chop HTML tags in half!
WordPress Content Function
Alternatively, we can also use the the_content() function in our themes. This behaves a little different than the_excerpt.
the_content - The Short Version
On list pages - the WordPress blog home page, category list pages, archive pages, and the search results page - the_content() displays the main content of your blog post, up until it encounters the break tag:
<!--m o r e-->
Once WP encounters the more break, it truncates the post and appends a "Read more..." link. This is the "short version." (Note: actual break tag doesn't have spacing between the letters. I'm trying not to break my blog :)
Unlike the more text for the_excerpt, the_content displays this link in a new paragraph. There is no class on the inserted paragraph, but there is a 'more-link' class on the link:
<p>< a href="http://yourblog.com/some-post#more-97" class="more-link">Test</a></p>
WP Note: It would be very helpful if these inserted paragraphs had a class on them, or better yet a custom class. It would be also be useful if the more-link had the option of being inserted inside the last paragraph, like the_excerpt's more text. Last but not least, it would be helpful if we could trigger whether or not the link jumps to the #more- anchor.
The text of the link is customizable by passing in a string, like so:
<?php the_content('Full Content Here...'); ?>
You can also override the more link text on a post by post basis, from with the editor. Just make the break tag like this:
<!--more Keep reading this post-->
FYI - There is a way to manually strip the #more- anchor jump out of link, and other techniques for overriding the more text - details here.
You can check to see if a post contains a break tag by using this
if ($pos=strpos($post->post_content, '<!--m o r e-->')) { // do something }
WP Note: it would be great to add a has_more_tag() conditional tag.
Be aware, the_content() doesn't filter out any HTML from the short version. So if you split your post in the middle of an HTML tag, you will have problems.
This page shares how to add HTML filtering to the_content.
the_content - The Long Version
If WP doesn't encounter the break tag, then it will display the post's entire contents - the "long version". On singular pages, the_content() ignores the break tag and displays the long version by default.
Overriding the Break Tag
The break tag can be overridden pretty easily. WordPress keeps track of the mode to use for the_content via a global variable called $more.
- When $more is set to 0, the_content() will display the truncated "short version" of a post.
- When $more is set to 1, the_content displays the whole post.
Here's some example code:
<?php
global $more;
$more = 1;
the_content(); // long version
?>
A Flexible Excerpt Snippet
Okay wait, this is really confusing and there's a lot of options - what's the best?
It all depends on the project and needs of your theme. Most of the time, you'll probably want to integrate a tool like Advanced Excerpt.
But if you'd like to stick with WP's built in offerings, here's a little template snippet you can use in your loop. This lets you define a global $more_text string, which is used no matter what. And there's a conditional to choose intelligently which excerpt to load.
I hope this guide has helped you navigate the mysterious world of WordPress post excerpts! Let me know if you have any questions.
