Blog Style Guide

So you’re writing for our blog. Awesome!

However, putting together articles is not all WordPress skills and witty turns-of-phrase. There’s a lot more to it as this style guide shows.

Please study these guidelines and refer to them when necessary.

Table of Contents

  • A Few Quick Things to Keep in Mind
  • Posting Checklist
  • Styling Images
  • Compressing Images
  • Embedding Videos
  • Adding Code Snippets With Gist
  • Social Media Profiles
  • Custom Post Types – Lists, Reviews and Comparisons

A Few Quick Things to Keep in Mind

There are few things you should be aware of if you’re writing for our blog:

  • We use US English and follow the Yahoo Style Guide, albeit loosely.
  • You don’t need to provide feature images for your posts – we’ve got talented designers who create custom images.
  • We have custom post types for posts that contain lists, review and comparisons. (You can read more about our custom post types at the bottom of this page.)
  • We use Gist for all code snippets. (You can read more about using Gist below.)

Posting Checklist

We use Good Writer Checkify to help contributors ensure posts follow a consistent style. Please ensure you’re able to tick off each item on the checklist before submitting a post.

1. Wrap First Paragraph With H2 Tags

First paragraph
The first paragraph of every post must be styled.

The first paragraph of a post must be wrapped in h2 tags.

This is a new feature of our updated website design that helps to draw readers into the article.

It also helps to quickly emphasizes what the post is about for our readers who simply skim the content, rather than read it in-depth.

Sub-headings within posts should use H3> tags. Please don’t use H2 tags for any sub-headings. Any sub-headings contained within H3> tags should use H4> tags, and any further sub-headings should be made bold.

 2. Add a MORE Tag After First Three/Four Paragraphs

Using tags ensures our subscribers only get a snippet of your post.
Using tags ensures our subscribers only get a snippet of your post.

We use more tags to ensure subscribers who receive our daily blog updates only get a short excerpt rather than full posts in their email.

To add a more tag to your posts, click the area in the post where you would like to add one and then click the “Insert Read More tag” button.

3. Comment Prompt at the Bottom of Posts

At the end of every post, please pose a question to readers to encourage them to leave a comments. Don’t forget to make it bold! For example:

Have you done any mods to your WordPress editor? Did you use code, plugins, or both? Have you used these or any plugins that I didn’t mention? Let us know in the comments below.

4. Categories

Choose a maximum of three categories for your post.

5. Tags

Choose a maximum of five tags for your post.

6. Related Posts

Related posts need to be, well, related. Unfortunately, YAARP doesn’t always pull up the best related posts and sometimes list posts that have been 301-ed and/or no longer exist. So it’s important to check the suggested related posts that appear in YARPP.

In the Post Editor, scroll down to the bottom to the Related Posts section and check out each of the posts that are listed.

Check that your related posts are relevant.
Check that your related posts are relevant.

Uncheck any posts that are irrelevant, more than 12 months old, or have been 301-ed.

Search Google for topics similar to what you have written about in your post. For example, if your post is about plugins for freelancers, search for “ freelance.”

Search Google if YARPP doesn't display any appropriate posts.
Search Google if YARPP doesn’t display any appropriate posts.

If any of the posts listed in Google search are a better match for your article, copy the post’s URL into the “Enter your post URL” text field and click “Add.”

Once you have three related posts you’re confident are relevant and complement your post, click “Save and Publish This Selection.” Make sure you save your selection otherwise the links will be wiped next time you save your post.

7. Excerpts

Entice readers with a short and sharp excerpt. It’s an important piece of text because it’s seen on search engines and social media sites like Facebook, Twitter and Google+.

Enter a short, two-line excerpt that summarizes your post.
Enter a short, two-line excerpt that summarizes your post.

8. Images/Videos Meet Size Requirements

We’ve customized the media uploader for our blog with a range of eight different image variations designed to provide a more interesting reading experience for visitors to our site.

Use a mix of images and alignments where possible. If you are trying to illustrate something important, you may want to use a large image, rather than a regular image, for example. You may also use a full-width, but only if the image is sharp.

Use a mix of image variations in your posts.
Use a mix of image variations in your posts.

The media uploader specifies the image widths you should use. Any height is fine, except for left/right images, which must use 490px x 312px images).

If you’re not sure what mix of variations to use, check out the latest posts on the blog.

Regular – 735px

These images sit inline with the blog content. Here’s an example:

Related posts
An example of a “Regular” image.

Large – 1364px

Large images take up more of the screen, though should always be 1364px. Use this size if you need to show a bit more detail in your posts.

Large image
This is an example of a “Large” image.
Left aligned
A left-aligned image.

Left – 490px x 312 pxLeft aligned images can further enhance the reading experience.When adding a left aligned image, the image uploader will create a table. Make sure you delete the placeholder text and write just enough of your own to fill the space next to the image so the last line sits almost flush with the bottom of the image, like so.

Right aligned image
An example of a right-aligned image.

Right – 490px x 312pxRight-aligned images are just like left-aligned images except they’re, well, on the right.Don’t forget to replace the placeholder text and enter enough text so it almost sits flush (give or take a few pixels) with the bottom of the image. It just looks better!

Fullwidth – 1364px

Now this is where things really start to get interesting. Fullwidth images are just that – fullwidth. Here’s an example:

Fullwidth dark bg – 1364px

There are also a couple of variations on the fullwidth image. The first offers a dark background, over which you can enter some text. You may want to enter a blockquote or just some interesting information you want to highlight.

When you upload an image, the text that’s shown over the top will be pulled in from the caption you write. In the backend of your post, the image will be displayed with a shortcode and you will be able to edit the displayed text.

The text below has been styled as a blockquote:

`Twas brillig, and the slithy toves
Did gyre and gimble in the wabe:
All mimsy were the borogoves,
And the mome raths outgrabe.

Fullwidth light bg – 1364px

There’s also a fullwidth variation with a light background. This may come in handy if you have a dark image over which you wish to place some text.

Tips for Your Images

Screenshot of the network requests shown in Google Chrome Developer Tools.
Screenshot of the network requests shown in Google Chrome Developer Tools.

Cropping Images

Don’t be afraid to crop images! You don’t need to include a full image to show readers details.

In this example, we’ve cropped an image to help illustrate the number of server requests in a post about optimizing WordPress.

Please don’t reduce images to fit our size dimensions as this will result in a blurry image. If an image you want to use doesn’t meet our size requirements, crop it. Another trick, if you’re taking a screenshot, is to zoom out on your browser and then take the screenshot.

Descriptive File Names

Ensure the file names of your images are descriptive, i.e. “chrome-developer-tools.png” or “wordpress-post-editor.jpg.” Image file names automatically become the title of your image in WordPress, therefore, don’t name it something like “pic0000324987” or “Screen Shot 2015-07-20 at 6.29.57 pm.”

Make Images Accessible

Also, add alt text to your images to ensure they are accessible to text/screen readers.

Screenshots and Annotations

No doubt you will need screenshots in your posts. If you don’t have a tool to do this already, Jing is free software you can use.

If you need to highlight/annotate an area of a screenshot, please use Jing. Draw a yellow square around the area you would like to highlight, as in the example below:

An example of how to correctly highlight an area of a screenshot.
An example of how to correctly highlight an area of a screenshot.

Jing is a free tool. If you’re not sure how to get started with Jing, here’s a great tutorial on taking your first screen capture.

Image credits

Ensure any images you use other than screenshots are free to use and available for commercial purposes. If you are using an image and not sure if you are allowed to use it, find its original source and check the license. If you can’t find any licensing information, don’t use it.

Check out The Best Places to Find Free Stock Images for Your WordPress Site – our guide to free stock images – for a list of some fantastic stock image sites.

You may need to provide attribution for any images you use from free sites, depending on licensing. Please display attribution at the bottom of your post like so:

Image credits: Unsplash, Picography.

Compressing Images

Here’s a quick guide to best practices for compressing images for our blog by Victor Ivanov, one of our designers.

The steps below are for Photoshop, but you can achieve the same results with any image software so long as you use the Save for Web option.

It is incredibly important that we compress images correctly for our website for two reasons:

  • Our images should always look as good as possible. We make legit, high-quality products, and our marketing assets need to reflect that.
  • Our awesome developers spend a lot of time making sure is super, super fast. Uploading huge, poorly compressed images essentially negates all their hard work.

1. Choose a Format Suitable for the Image

Here’s an example of a poorly compressed image:

A poorly compressed image.
A poorly compressed image.

It’s 342kb, which is outrageous for an image of this size. The reason here is that the PNG format is not suitable for this type of image.

Here’s rough rule of thumb: Use JPGs for photographic images and PNGs for images with a limited number of colors.

For example, a picture of the WordPress admin, a paragraph of text or an illustration with a few colors should be a PNG, whereas an iPhone photograph of your dog catching a frisbee whilst doing a backflip should be saved as a JPG.

If you’re not sure whether to use JPG or PNG, just test what looks best without generating a massive filesize. It’s really easy and you should pretty much become an expert in the first few tries!

So coming back to the aforementioned image, you can see that there is quite a lot of photographic detail (the noisy backgroud). I saved it as an 80% Progressive JPEG and managed to cut the size down to 90kb from the original 342kb. That’s about 3.8x smaller and the best part is the quality difference is imperceptible.

2. Always Follow Our Image Sizes Guide

Again, our superb developers have actually added image variations into the image media uploader UI. It is impossible to miss.

You should always save and upload images at the corresponding sizes. Doing so ensures that WordPress will not automatically re-size and compress the image further, resulting in poor quality. An exception here can be made for animated GIFs, as those can be quite tricky to get the exact size.

3. Always Save As Progressive Image

Progressive images are faster, smaller in size and are just better. They are a clear win-win.

Progressive images first load pixilated and over time, become clearer. This is also a win because this creates an illusion of super fast page (as well as actually making page faster). Perceived performance is probably even more important than actual performance. Here’s a gif that demonstrates Progressive JPEG load.

4. Using Image Composition / Direction

Using the correct images sizes for the image variations on the blog will help you achieve a good quality image that isn’t re-sized by the browser, and is thus crisp. Additionally image quality is improved by focusing on the core elements you are trying to show, i.e. capturing the details in the image you want to show:

An example of image composition / direction that focuses on the core elements of what you are trying to show.
An example of image composition / direction that focuses on the core elements of what you are trying to show.

For this 490 x 312 picture of our image variations to the right, I simply took a screenshot of the media uploader, ensuring I captured a 490 x 312 rectangle.

I then opened the resulting image in Photoshop to optimize it and save it.

Typical settings for saving a JPG image.
Typical settings for saving a JPG image.

I used Photoshop’s Save for Web feature to save the image with the settings in the image to the left.

The resulting image is sharp and optimized.

In a blog post this image would look crisp, and our blog won’t try to automatically optimize the image further.

Typical settings for saving a PNG image.
Typical settings for saving a PNG image.

For images that use few colors, it’s best to save in PNG format.

For the image to the right, which uses few colors, I used the PNG settings captured in the image. The resulting image is only 12KB and displays sharply on screen.

Never resize images in Photoshop after you’ve taken a screenshot, as this will always result in a blurry image.

Instead, take a screenshot using the dimensions you need for the image, as demonstrated in the three images above.

Using the zoom feature on your browser can help with image composition / direction, ensuring the area you want to capture is the correct size. For example, if you need to take a screenshot of the homepage of a website, zoom out as much as you can with your browser and then resize the window, like so:

A crisp screen grab of our homepage.
A crisp screen grab of our homepage.

The above image was screen captured in a browser that was zoomed out to 67%. The window was resized so the page could be captured at 735 x 385.

If you have any further questions about image optimization or are unsure about a specific image you want to include in a post and need advice, please ask! Following the advice in this guide will ensure your images are always sharp and look great on the blog.

Embedding Videos

When embedding videos in posts, ensure width is set at 735px and the height is 415px.

Don't forget to update the height and width for your videos.
Don’t forget to update the height and width for your videos.

Adding Code Snippets With Gist

There are two ways to use code within a post: within a paragraph to make a point about code that is being discussed, or as a highlighted block of code.

Code Within Paragraphs

Use the <code> tag to distinguish text that is computer code and not natural language.

For example, when writing about a WordPress function like wp_title(), switch to the Text Editor and wrap the function in <code> tags.

Blocks of Code

For longer blocks of code, use Gist to ensure your code displays correctly and the Post Editor doesn’t strip any characters.

If you haven’t used Gist before, it’s a simple way to share snippets and pastes with others. All gists are Git repositories, so they are automatically versioned, forkable and usable from Git.

Create Gist.
Create a new Gist.

To use Gist:

  1. Go to Gist and sign up for an account.
  2. On the Gist main page, give your code snippet a description and a file name, then select a language for your code.
  3. Paste your code snippet into the text area.
  4. Click “Create public Gist.”
  5. On the next page, copy the URL for your Gist.
  6. Paste the URL into your post where you want your code snippet to display. Ensure the URL doesn’t have any formatting.

The resulting Gist code snippet will look like this:

Social Media Profiles

If you don’t have a Google+ profile, please get one and connect it to Here’s how to do it:

In the admin area, go to Users > Your Profile > Enter Your Google+ URL (for example, our CEO James Farmer would use:

In Google+, add to your profile by going to the About section in your profile and in the “Links” section click “Edit.” Then in the “Contributor to” section add

Custom Post Types

We have three custom post types for displaying content on the blog:


The List post type provides a neat way to display plugin and theme lists, as well as lists of other products and services.

The custom post type for lists.
The custom post type for lists.

To create a new list:

  1. Go to Lists > Add New.
  2. Give your list a title.
  3. Add a feature image. All feature images must be 735px by 210px.
  4. Add a description for your list item in the main text area.
  5. In the “Buttons” section, name your button and than paste in a URL. Generally, it’s best to name the button “Details” unless you want to be more specific or you need more than one button. For example, a theme post may have buttons for “Details,” “Demo” and “Download.”
  6. To add another item to your list, click “Add New List Item” at the bottom.
  7. When you’ve finished creating items for your list, click “Publish”.
  8. Copy the shortcode that is generated below the “Publish” button and paste it into your original post where you want to display your list.

Your list will look similar to this: 50+ Quick Setup Portfolio WordPress Themes.


The Reviews post type provides a way to display in-depth reviews of products and services complete with star ratings, and our opinion of the good and bad aspects of a particular product or service.

The custom post type for reviews.
The custom post type for reviews.

Creating a review is similar to creating a new post.

To create a review:

1. Go to Reviews > Add New.

2. Give your review a title.

3. In the post area, write your review.

4. At the bottom of the Post Editor, fill in your review information with Good, Bad and Bottom Line information.

Provide Good, Bad and Bottom Line information for your review.
Provide Good, Bad and Bottom Line information for your review.

5. In the Review Ratings section, give the product/service you are reviewing ratings out of 10. These will be converted to ratings out of five when displayed as stars on the blog.

Give your review star ratings.
Give your review star ratings.

6. When you’ve finished your review, click “Publish”.

7. Copy the shortcode that is generated below the “Publish” button and paste it into your original post where you want to display your review.

Your review will look similar to this: Drag and Drop Review Redux: Divi by Elegant Themes.


The Comparison post type draws information from the Reviews post type and is used to create a table comparing several reviews.

Check out Choosing a WordPress Theme Framework – the Ultimate Guide” and scroll to “Theme Frameworks Compared” at the bottom of the page to see the Comparison post type in action.

To create a comparison:

1. Go to Comparison > Add New.

2. Under “Comparison Items,” enter the names of the reviews you want to compare. When you start typing, the field will ask you to autocomplete. Click “Add” to add the review to your comparison.

Add reviews to compare.
Add reviews to compare.

3. The “Comparison Reviews” section allows you to compare each of the reviewed produces/services against each other and give them ratings out of 10. You can add open or more review ratings sections, depending on how many elements you would like to compare. For example, if you are comparing several theme shops on their prices, usability and support, you would add comparison ratings for “Prices,” “Usability” and “Support.”

Copy the shortcode at the bottom of the section and paste it into your original post.
Copy the shortcode at the bottom of the section and paste it into your original post.

4. The “Comparison Overall” compiles all of the ratings you have entered in the other sections and produces a table with an overall rating for each reviewed product/service. Here, you can specify how many columns to display the resulting table.

The comparison post type create an overall table comparing products/services you have reviewed.
The comparison post type create an overall table comparing products/services you have reviewed.

5. For each section, copy the shortcodes that are produced and paste them into your original post. Preview your post to ensure they display correctly.