Listing category names beside their descriptions is not something WordPress offers an easy solution to within the codex, though it sounds easy enough. WordPress' wp_list_categories will add the description to the category name link as a title tag replacing the default "View all posts filed under CategoryName". Unfortunately, we ran into this issue while building a client web site and after several hours of research into the matter and altering the core to suit our needs, we at last discovered the beauty of get_categories.

The goal of this tutorial is to demonstrate the use of get_categories to echo both the category name and it's description side by side. From the WordPress codex: 'get_categories' "returns an array of category objects matching the query parameters. Arguments are pretty much the same as wp_list_categories and can be passed as either array or in query syntax."

We will be covering both the alteration of the WordPress classes.php file and demonstrate the get_categories function to achieve the desired results.

Classes.php Core Alteration:

This method is a little on the risky side as it can easily be deleted during a hasty WordPress upgrade and, as such, we do not recommend it. We are presenting this core alteration as a learning experience only.

Begin by locating the classes.php file within the wp-includes folder. At the time of this article, we are using WordPress 2.9.2 so the line number may vary with a newer release but we are looking for the 'start_el' function on line 1325:

function start_el(&$output, $category, $depth, $args) {
extract($args);

$cat_name = esc_attr( $category->name);
$cat_name = apply_filters( 'list_cats', $cat_name, $category );
$link = '<a href="' . get_category_link( $category->term_id ) . '" ';
if ( $use_desc_for_title == 0 || empty($category->description) )
 $link .= 'title="' . sprintf(__( 'View all posts filed under %s' ), $cat_name) . '"';
else
 $link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"';
 $link .= '>';
 $link .= $cat_name . '</a>';

In the function above, we can see the "category_description" is placed within a 'title' tag of the link which begins on line 6. We want to alter this function to instead display the "category_description" within its own 'div' tag and not the 'title' tag. With a few alterations to the function, it is possible to add additional code modifying it to display the description outside of the link. The example below is one of many ways to achieve this.

function start_el(&$output, $category, $depth, $args) {
extract($args);

$cat_name = esc_attr( $category->name);
$cat_name = apply_filters( 'list_cats', $cat_name, $category );
$link = '<a href="' . get_category_link( $category->term_id ) . '" ';
if ( $use_desc_for_title == 0 || empty($category->description) )
 $link .= 'title="' . sprintf(__( 'View all posts filed under %s' ), $cat_name) . '">' .$cat_name . '</a>';
else
 $link .= '>' . $cat_name . '</a><div class="myClass">' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '</div>';

The example above allows for two potential outputs. The first output assumes that we have not included a description for our category and, as such, the result is exactly as WordPress intended. The category name is echoed as a link and the 'title' tag's output is "View all posts filed under CategoryName". The second output relies on the fact that we have included a description for our category. In this situation, the category name is echoed as a link and below this is a 'div' tag with a class of "myClass" echoing the description. Keep in mind this is not a necessary course of action as there is an easier and not core-altering option which will produce the same result.

Get_Category Function Alternative:

The easier and more desirable option, just shy of a plugin, is to use the following get_category function.

<ul class="myClass">
 <?php $categories = get_categories('number=10');
 foreach ($categories as $cat) {
 echo "<li><a href=\" . get_category_link( $cat->term_id ) . "\">" . $cat->cat_name . "<div class=\"description\">". $cat->description ."</div></a></li>";
 } ?>
</ul>

Here we are calling on the first ten categories through the use of the 'number' parameter within the array and cycling through each of the categories. We are then passing along the line item, link, category name, description and so forth, providing a nearly identical output as wp_list_catgeories but with the twist of allowing for the option to echo the description as text and not as a 'title' tag.

The WordPress codex provides a total of eleven parameters to use within the array including: 'child_of', 'orderby', 'order', 'hide_empty', 'exclude', 'include', include_last_update_time', 'hierarchical', 'number' and 'pad_counts'. For more information please refer to the function reference for get_categories.