Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Linking Posts Pages and Categories

There are two ways to make internal links from one content page to another in WordPress. One uses permalinks and one does not. The method that does not use permalinks works regardless of whether permalinks are enabled for your site.

Linking Without Using Permalinks

If you are not using Permalinks, how do you link to your posts, categories and Pages?

Using the numeric values such as Post ID, Category ID and Page ID, you can create links as follows.

Posts

The Post ID is revealed as part of the URL in the form of "...?post=89", and that URL is displayed in the browser status bar by hovering the mouse over the Post Title of the target Post in the Posts Screen. Insert it in place of the '123' in this link:

<a href="/index.php?p=123">Post Title</a>

Categories

The Category ID is revealed as part of the URL in the form of "...&tag_ID=3", and that URL is displayed in the browser status bar by hovering the mouse over the Category Name of the target Category in the Categories Screen. Insert it in place of the '7' in this link:

<a href="/index.php?cat=7">Category Title</a>

Pages

The Page ID is revealed as part of the URL in the form of "...?post=15", and that URL is displayed in the browser status bar by hovering the mouse over the Page Title of the target Page in the Pages Screen. Insert it in place of the '42' in this link:

<a href="/index.php?page_id=42">Page title</a>

Date-based Archives

To link to a given year of a date-based archive, replace the '2015' part of the below link with the required year.

<a href="/index.php?m=2015">2015</a>

You can also link to a specific month by appending the month to the year in the format YYYYMM, or link to a specific day using the format YYYYMMDD.

<a href="/index.php?m=201501">Jan 2015</a>
<a href="/index.php?m=20150101">Jan 1, 2015</a>

Links On External Sites

If you are providing a link to your site from outside of your site, be sure to specify a full URL to the correct location:

<a href="http://example.com/index.php?p=123">post title</a>

If you have installed WordPress to a subfolder, such as wordpress, don't forget to add the folder to the link URL:

<a href="http://example.com/wordpress/index.php?p=123">post title</a>

Linking Using Permalinks

If you are using permalinks, you can use all of the above non-permalink techniques, which will work with permalinks enabled or not. If you have enabled permalinks, you have a few additional options for providing links that readers of your site will find a bit more user-friendly than the cryptic numbers.

The complexity of the URL depends on the complexity of your permalink configuration. If your permalink configuration (set on the Options > Permalinks Administration Screen) contains many Structure Tags, then the URL will be more difficult to construct.

Posts

For posts, replace each Structure Tag in your permalink structure with the data appropriate to a post to construct a URL for that post. For example, if the permalink structure is:

/index.php/archives/%year%/%monthnum%/%day%/%postname%/

Replacing the Structure Tags with appropriate values may produce a URL that looks like this:

<a href="/index.php/archives/2005/04/22/my-sample-post/">My Sample Post</a>

To obtain an accurate URL for a post it may be easier to navigate to the post within the WordPress blog and then copy the URL from one of the blog links that WordPress generates.

Review the information at Using Permalinks for more details on constructing URLs for individual posts.

Categories

To produce a link to a Category using permalinks, obtain the Category Base value from the Options > Permalinks Administration Screen, and append the category name to the end.

For example, to link to the category "testing" when the Category Base is "/index.php/categories", use the following link:

<a href="/index.php/categories/testing/">category link</a>

You can specify a link to a subcategory by using the subcategory directly (as above), or by specifying all parent categories before the category in the URL, like this:

<a href="/index.php/categories/parent_category/sub_category/">subcategory link</a>

Pages

Pages have a hierarchy like Categories, and can have parents. If a Page is at the root level of the hierarchy, you can specify just the Page's "page slug" after the static part of your permalink structure:

<a href="/index.php/a-test-page">a test page</a>

Once again, the best way to verify that this is the correct URL is to navigate to the target Page on the blog and compare the URL to the one you want to use in the link.

Date-based Archives

To permalink to a given year of a date-based archive, append that year to the archive's base link. For example, to link to the year 2015 in an archive with the base link /index.php/archives/ you would use:

<a href="/index.php/archives/2015">2015</a>

You can also permalink to a given month or date by appending month and day values to the corresponding year.

<a href="/index.php/archives/2015/01/">Jan 2015</a>
<a href="/index.php/archives/2015/01/01/">Jan 1, 2015</a>

Links on External Sites

Permalink structures should begin with a slash, meaning that they are anchored at the root of the site's URL. You should be able to prepend the protocol and server name to any link that begins with a slash to build a successful full URL.

For example, this category link:

<a href="/index.php/categories/parent_category/sub_category/">subcategory link</a>

Becomes this category link using a full URL:

<a href="http://example.com/index.php/categories/parent_category/sub_category/">subcategory link</a>

Combining Links with Template Tags

You can customize your links in the header, footer, or sidebar to be combinations of link types. This example features links to two categories, the main index page, a post, a static page, and uses the Pages template tag.

Note carefully that the wp_list_pages() template tag generates its own List Item (LI) so it doesn't need to be wrapped in a LI tag. This template tag is also set to list only the parent Pages and not their subPages or "children".

<ul id="linklist">
 <li>
  <?php _e('Check It Out'); ?>
  <ul id="pageslist">
   <li>
    <a title="Home Page" href="index.php">Home</a>
   </li>
   <li>
    <a title="Blog" href="index.php?cat=7">Blog</a>
   </li>
   <li>
    <a title="Life Story" href="index.php?p=12">My Life Story</a>
   </li>
   <?php wp_list_pages('exclude=4&depth=1&sort_column=menu_order&title_li='); ?>
   <li>
    <a title="Links and Resources" href="index.php?cat=33">Links</a>
   </li>
   <li>
    <a title="Site Map" href="sitemap.php">Site Map</a>
   </li>
  </ul>
 </li>
</ul>

Using such a customized list, you can also add CSS classes to change the look of each of the links, or style the entire section. It's up to you.

Absolute versus Relative Links

Absolute links define absolutely where to find the target of the link.
Relative links define the location of another document in relation to the current document.

Absolute Link Examples

Full URIs of the form http://example.com/wordpress/index.php are absolute links.

Absolute links can also point to your own server. When doing so, you may safely omit the http://domain.com prefix, and link to the target with a full path:

/wordpress/index.php

The leading slash means "At the very top of this domain is a directory named wordpress, and inside this directory is a file named index.php".

A document at

http://example.com/wordpress/index.php

contains a link of the form

/wordpress/index.php

The link above, when clicked, will take the viewer to

http://example.com/wordpress/index.php

Relative Link Examples

Relative links do not start with a slash:

wordpress/index.php

The lack of a leading slash means "Inside the current directory is a sub-directory named wordpress, and inside that directory is a file named index.php".

A document at

http://example.com/wordpress/index.php

contains a link of the form

wordpress/index.php

The link above, when clicked, will take the viewer to

http://example.com/wordpress/wordpress/index.php

Let us consider the case where in our blog where we are editing

http://example.org/blog/2015/01/04/nurds-on-the-loose

From it we can make links

  1. <a href="../01/happy-new-year">New Years Announcement</a>
  2. <a href="../../01/01/happy-new-year">New Years Announcement</a>
  3. <a href="../../../2015/01/01/happy-new-year">New Year's Announcement</a>
  4. <a href="../../../2014/12/25/merry-christmas">Christmas Announcement</a>

Note 1, 2, and 3 are all valid to achieve the same link. However with 4 there is no shortcut, as we must "climb" all the way into the previous year.

The links are all relative and we need not hardwire in any more knowledge than is necessary, which also will help portability if one day we export the blog elsewhere. (What happens if one day we however pick a different permalink structure via the administration screens is unknown...)

However, the above assumes we are always viewing a single post. If in fact we are viewing that same post in an archive, well, then all our assumptions of where we are now are wrong! So we see that however smart relative linking looks, it has a fatal flaw and cannot be chosen!

For more information on absolute and relative links, see the WebReference Tutorial on Absolute and Relative Links.

Dynamic Linking in Templates

Whether you use permalinks or not, in templates you can link to pages or posts dynamically by referring to its unique numerical ID (seen in several pages in the admin interface) with <a href="<?php echo get_permalink(ID); ?>">This is a link</a>. (as shown in Template_Tags/get_permalink)

This is a convenient way to create page menus as you can later change page slugs without breaking links, as IDs will stay the same. However, this might increase database queries.

Dynamic page menus can also be created by utilizing Template_Tags/wp_list_pages child_of parameter or some of the many available plugins.

RSS

It seems that only fully qualified links (http:...) are guaranteed to work in all RSS reading environments...