So you’re writing for our blog. Awesome!
However, putting together articles is not all WordPress skillz 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.
Headings/Sub-Headings – Make sure they are short, literal, error-free, catchy and click-worthy. Headlines are also likely to be changed during the editing process. Read more.
Category – Choose a maximum of three categories, though you may only want to use one.
Tags – Choose a maximum of five tags.
Feature Images – Our designers create custom featured images for all our posts, so you don’t have to worry about inserting one. Read more.
Custom Excerpt – Create a brief and concise custom excerpt that will draw visitors in from search engines and social media sites. Read more.
Styling Posts – Use short paragraphs, bullet points and blockquotes to break up big chunks of text. Read more.
Style and Grammar — We follow US English and use the Yahoo Style Guide, albeit loosely.
Styling Images (and Cropping and Compressing Them Properly) – Use images for instructional purposes or to break up text and provide a more interesting reading experience. Read more.
Embedding Videos – Use videos to add another visual element to your posts. Read more.
Social Media – All posts are scheduled to go out to our Facebook, Twitter and Google+ accounts. You don’t need to worry about updating WordTwit in the Post Editor. Read more.
Social Media Profiles – Make sure your Google+ profile lists you as a contributor to the WPMU DEV Blog. Read more.
Related Posts – Check that the related posts are relevant. Read more.
Code Snippets – Use Gist for all code snippets. Read more.
In-Post Ads, Front Page Excerpt, Infinite SEO – You don’t need to worry about these settings.
Custom Posts – We have three custom post types – Lists, Reviews and Comparisons. Read more.
Focus the title of your post. If you don’t write your title to be accessible to search engines (under 70 characters with the main keyword near the front of the title), you can insert an optimized title into the “Infinite SEO” meta box.
The meta box allows you to add a search engine accessible title – we want to make sure Google users get the best possible experience. Search engines will see that title as will search engine users. So make it both accessible and extremely reader-friendly as well.
Having said all this, post titles are likely to be changed during the editing process, so please don’t update the information in Infinite SEO.
Your original title (not the one in the Infinite SEO box) will be seen on our blog, as well as in in RSS feeds, on Facebook, Google+, Twitter, etc. This means it’s important to make your title human readable. Try to entice readers into the post with your title.
While making your title accessible to search engines is less important in the original title, you should also try to include your keywords in it if possible (or variations of your keywords — write for humans first). Search engines will pick up links from that title out on social media sites, and so it’s important to tell them what the post is about. It’s also important that this title has at least one word in it that is WordPress-related, such as WordPress, BuddyPress, Multisite, plugins, themes, etc. This will help people who are looking for WordPress info to identify your post as something WordPress related.
Our designers create tailor made images for all our posts, so you don’t need to set a feature image.
For reference, the dimensions for feature images are 735px by 210px.
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+.
Ensure your posts are easy to read by breaking up text into smaller chunks. Keep in mind that people often scan text on the web rather than read long paragraphs.
You can break posts up in a number of different ways. Use the following:
- Bullet points or numbered lists
- Bold or italicized text
- Short paragraphs
People are used to reading much shorter paragraphs on the web compared to paper. Therefore, don’t be afraid to break a traditional paragraph up into several smaller paragraphs of a 1-3 sentences.
First Paragraph of Post
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> for any sub-headings. Any sub-headings contained within <h3> tags should use <h4> tags, and any further sub-headings should be made bold.
At the end of every post, please pose a question to readers to encourage comments, and 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.
Add a <more> tag after the first three or four paragraphs of your posts. This will ensure subscribers who receive daily blog updates will receive a short update about your content rather than the full post.
Please refrain from the excess use of exclamation marks. An editor once said to me, “Everyone is entitled to two exclamation marks during their life time. Use them well.”
Use images to illustrate a point (a picture tells a thousand words!) and provides a more interesting reading experience.
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 fullwidth, but only if the image is impressive and high resolution enough.
Using the Custom Media Uploader
We’ve customized the media uploader to suit our blog design.
There are eight images variations to choose from and you must upload an image with the corresponding width. Any height is fine (except for left/right images), as long as it doesn’t look ridiculous.
Regular – 735px
These images sit inline with the blog content. Here’s an example:
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.
Left – 490px x 312 px
Left 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 – 490px x 312px
Right-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.
While the image below doesn’t meet the dimension requirements for our blog, I’m using it as an example of how magnifying a select part of an image can help illustrate a point.
If you must use a large screenshot to appropriately illustrate the functionality of a product or service, it’s okay to upload the image to your post, but make sure the image links to its own URL in the media library. This will allow readers to access a larger version of the image. In the image caption, add: “Click to see a larger image.”
Make Images Accessible
Add descriptive file names and alternative text to your images to ensure they are accessible to text/screen readers.
Name your image something appropriate. The name of your image file will also 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.” Name it something appropriate such as “youtube-featured-video-popup.”
Alternative text, also known as “alt text,” is an opportunity for you to describe your image in a short sentence or phrase. When you do this, think of how you would describe your image (in the context of your post) to someone who is visually impaired.
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.
In order to highlight an area of a screenshot, please use a yellow outlined shape such as a yellow square or a yellow circle. Please do not use arrows or shadows.
Ensure Images Are Not Linked
When adding new images to a post in the media library, make sure it doesn’t link to another website or its own URL:
This is especially important for posts that use the custom and review list post types.
Make sure 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:
By Victor Ivanov, WPMU DEV Product Guy
This is a quick re-fresher course on best practices for using images on our blog. The steps below are for Photoshop, but you can achieve the same results with any image software.
It is incredibly important that we follow the rules below 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 tim making sure wpmudev.org 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: http://premium.wpmudev.org/blog/wp-content/uploads/2015/06/wp-optimize.png
It’s 342kb, which is outrageous for 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 use 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 noisey bg). 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 Media Manager 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 pixillated and over time, become clear. 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: http://media.mediatemple.netdna-cdn.com/wp-content/uploads/2015/06/13-progressive-jpeg.gif
That’s basically it. The third rule is new, I have not mentioned it before, but it is super relevant and we should all be using it. Also, I realize not everyone uses Photohsop, but I am certain that any decent alternative graphics software should also have all those Save For Web settings.
Videos should be embedded in posts using iFrame. When embedding videos from Wistia, for example, choose “iFrame” under embed type:
Under “Video Size,” the maximum width should be 735px. The height of the video is up to you. After you embed your video, preview how it looks on the blog and edit the video size in the Text Editor to ensure it has appropriate dimensions.
If you don’t have a Google+ profile, please get one and connect it to premium.wpmudev.org/blog. Here’s how to do it:
In the premium.wpmudev.org/blog admin area, go to Users > Your Profile > Enter Your Google+ URL (for example, our CEO James Farmer would use: https://plus.google.com/100867129079471807437/posts).
In Google+, add premium.wpmudev.org/blog 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 premium.wpmudev.org/blog
Related posts need to be, well, related. Unfortunately, YAARP doesn’t always pull up the best related posts and can 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.
1. In the Post Editor, scroll down to the bottom to the Related Posts section and check out each of the posts that are listed.
2. Uncheck any posts that are irrelevant, old or have been 301-ed.
3. Search Google for topics similar to what you have written about in your post. For example, if your post is about popular post plugins, search for “site:premium.wpmudev.org/blog popular post plugins.”
4. 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.”
5. Once you have three related posts you are 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.
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.
To use Gist:
- Go to Gist and sign up for an account.
- On the Gist main page, give your code snippet a description and a file name, then select a language for your code.
- Paste your code snippet into the text area.
- Click “Create public Gist.”
- On the next page, copy the URL for your Gist.
- 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:
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.
To create a new list:
- Go to Lists > Add New.
- Give your list a title.
- Add a feature image. All feature images must be 735px by 210px.
- Add a description for your list item in the main text area.
- 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.”
- To add another item to your list, click “Add New List Item” at the bottom.
- When you’ve finished creating items for your list, click “Publish”.
- 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.
Creating a review is similar to creating a new post.
To create a review:
- Go to Reviews > Add New.
- Give your review a title.
- In the post area, write your review.
- At the bottom of the Post Editor, fill in your review information with Good, Bad and Bottom Line information.
- 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.
- When you’ve finished your review, click “Publish”.
- 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:
- Go to Comparison > Add New.
- 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.
- 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.”
- 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.
- For each section, copy the shortcodes that are produced and paste them into your original post. Preview your post to ensure they display correctly.