Creating an Advanced Attachment Page in WordPress

Creating an Advanced Attachment Page in WordPress

Images are often used to make posts more welcoming and to help illustrate a point, but despite their widespread use the attachment page is sadly overlooked.

The attachment page is a page dedicated to a simple attachment, such as an image. Many themes don’t create a specific view for attachments, which means you website and users miss out on a potential information source, and potential SEO gain.

In this article I want to introduce you to attachment pages and show you how to create your own.

Continue reading, or jump ahead using these links:

What Is an Attachment?

In WordPress, an attachment is an uploaded item. This may be an image, a zip file, a movie or a PDF document. Attachments are stored in the posts table, the same place where regular posts and pages are stored.

In fact, attachments are posts but they have a different post type – attachment. This method of storage provides easy access and querying, which translates to easier development and faster processing.

What Is an Attachment Page?

An attachment page is a singular type page. Singular page is an umbrella term, which encompasses different types of single pages such as the single post page and single custom post type pages. Since an attachment is a post, it too has a single page. This is called the attachment page.

Your single post page is dedicated to your article. It displays the title, content, metadata, comments and so on. In a similar vein, your attachment page should be dedicated to the attachment shown. If it is an image it should show the title, the image, description, perhaps even comments and other information about the image.

How Is an Attachment Page Displayed?

Each page in your WordPress installation uses a template file to display its content. To determine which file is used we can use the template hierarchy.

If themes go to the trouble of creating a dedicated file for the attachment page view it will be named attachment.php. Many themes omit this, which means that the fallback file is used: single.php.

In itself this is not necessarily a problem. Some single pages are built in a way that supports good attachment views without any extra code. Some single pages have “if” statements, which modify how the single page acts if an attachment is being displayed.

Regretfully, theme authors don’t really bother with this page. They usually let it fall back on the single page template, which produces weird results:

image in X theme

This screenshot from the ever-popular X Theme shows the attachment page, which isn’t great. There is no information about the image and it is shown as a small thumbnail, even though the image is actually pretty big. In addition, the meta section has a bit of information left out, hence the double slash separator.

Theme authors can and should do better. Attachment pages can be highly customized to show previous and next image links, metadata related to the image and more. Take a look at the example below from my own website running Twenty Fifteen, the default WordPress theme.

Twenty Fifteen attachment page

The image is shown as big as possible with the description underneath. It is shown as large as possible within the confines of the container and the original resolution is shown in the meta section. Not pictured here is the comment form and a link to the post in which the image was published. That’s much better!

How to Find An Attachment Page?

The easiest way to find an attachment page is to go to the media section in any post edit page. In the same facility that allows you to insert an image, you should see a “Link To” setting. Switch this to attachment page and the URL box will show you the attachment page URL.

Attachment page link

You can also kind of guess it from the image name if you know which post it is attached to, and your website is using pretty permalinks.

If the URL of your post is “” and the image file name is something like “my-image.jpg,” it is probable that the URL of the attachment page for the image is “”

How to Create an Attachment Page

As an example, I will be using the freely available Hueman Theme, which is great, but doesn’t have a nice attachment view.

Attachment page in Hueman

The Attachment Page File

Before we get started, you’ll need a child theme before making any modifications.

This is where things get a bit tough because you need to copy the structure of your existing theme where possible to ensure your new template is visually consistent with the parent theme.

How easy/hard this is has a lot to do with how clearly your theme is coded. Many themes have difficult to follow code, which may make this process a lot more difficult.

First, create an attachment.php file in your child theme. You can verify that this file is being used by visiting an attachment page. It should be blank, since the file is empty. Then, switch to the parent theme and copy the full contents of the single.php file and paste it into your new attachment.php file. If you visit the attachment page again it should be back to how it was since it is using the same code as before, just from a different file.

Customizing the Attachment Page

What we want to do is leave as much intact in this file as possible. Taking a look at the code it seems that what we need to change is the stuff between the .post-inner element. At the time of writing, this means everything from line 12-27 in this file. Here’s how it looks now:

Let’s create a structure where the image is shown on top, followed by the title and description. Let’s get rid of the meta section and we don’t need to worry about post formats here so we can delete that stuff as well.

The code above shows the modified content that goes between the start and end tag of the .post-inner element. I used the wp_get_attachment_image() function to grab the image. I supplied the ID of the current post – remember this is the ID of the image since we are on an attachment page – and I used the large image size.

I then have the title and the entry in the same format as the theme originally had it in. I removed the meta section and the in-post pagination. This already looks a lot better:

Hueman Better Attachment

We could leave it at that but I thought I’d show you the beginnings of how you can create something more elaborate. Let’s output some links to different image sizes for easy downloads.

Using the wp_get_attachment_metadata() function we can view a list of all image sizes and simply walk through them using a loop. Here’s one way to do it:

I just modified the content of the .entry section. I added a new element to display resolutions. I retrieved the defined image sizes using get_intermediate_image_sizes() and added the “full” size to it. “Full” is not a defined image size, it is simply the full image, so if we want to show a download link separately it must be added.

The rest is a simple loop, which goes through the image sizes and retrieves the height, width and link for each image. I used this data to construct some links and echo them at the end.

Attachment Image Sizes


Attachment pages are great because they give you an opportunity to offer something valuable to your readers: More information about your images, your thoughts on them, perhaps download links or even information about the camera and techniques used to capture it.

Rich information such as this ranks highly in Google if used consistently and correctly, which means it is far more than just eye-candy.

If you don’t have an attachment page yet, I recommend following this guide and creating one now. You can also download the Hueman child theme I created to make this happen, although it will only be useful if you actually use Hueman as the parent theme.

Do you find attachment pages useful? Let us know what you think in the comments below.