Blog Post Style Guide

This is a demo post to help highlight all of the different blocks & formatting options available inside of blogs.

Categories & Tagging

You should always mark your posts with relevant categories. You can add as many of these as are relevant to the post. This will help improve which related articles are shown at the end of the post.

Feel free to add new categories if none of the existing ones apply but avoid creating niche subcategories.

Tags are not used for filtering or any functionality on the site at this time but feel free to add them if you wish.

Featured Image

The featured image will always be shown in a 16/9 aspect ratio. As with all images, feel free to make it any sizes as the site will auto-generated a range of sizes for performance reasons. Avoid images less than 1000 pixels wide and larger than 2500 pixels wide.

Introduction

The above the fold text in the header is taken from the article’s excerpt. WordPress will automatically take the first couple lines of the blog’s content but you should try and provide a more tailored excerpt. This well help stop situations where the content is cut-off awkwardly. You can edit the excerpt in the post’s sidebar.

Formatting

Lists

If you’re writing multiple paragraphs that are less than one line of text, consider if they would be better suited as a list. You should try and keep bullet points to less than one line of text long. If your list has less than three items it might be better as a fully written sentence.

Lists can be nested to allow for sub-lists but you should avoid creating lists with a depth higher than two as this becomes confusing and the indentation makes the text increasingly cramped.

1. Lists can be numbered.
2. But they should only be numbered if they follow a specific sequence.
3. For example, the steps in a recipe.

If your content does not need to follow a specific order then use a bulleted list. This is available in three possible styles: dashed, asterisk and disc. This is purely a stylistic difference and you should try and stick to one style across a single post unless you’re giving the styles specific meaning. For example, asterisks might denote important or dangerous items.

• My list is very important.
• My list deserve specific emphasis.

Bold & Italic

Bold & italic styling is available but should be used very sparingly. Making too much text bold makes the content harder to read and causes all of it to be less emphasised.

Use bold text for important details you don’t want the reader to miss and italics for creating tonal emphasis, such as inflection. Think of it like this: use italic for individual words and bold for sentences or larger phrases. You should never alter the font weight of headings by making them bold or italic.

Spacing

The site will automatically handle the spacing for headings, paragraphs and the blog specific blocks. Always preview your posts on the front-end before trying to mess with the spacing. You may experience spacing issues in the editor that don’t exist in the public version.

If you have a specific spacing need then the Spacer block is enabled but this should be used very sparingly. You should avoid using empty paragraphs for spacing, however a single empty paragraph is permitted before H2 headings if the content needs a clearer separation.

Headings

Headings are a great way to break up your content. You should start at the H2 level since the post title will be the H1 on the page.

Subheadings

To help readers understand their place within the headings, sub-headings of H3 or lower will have these little indented marks. These indicate that this heading is a sub-heading of a higher heading and are clearer than differentiating just by font weight and size.

Maximum Depth

The indentation treatment stops after the H4 depth. You should try not to use headings deeper than H4 as it causes confusion for readers.

Table of Contents

Headings of level H2 will appear in the table of contents in the right-hand side. ID’s are automatically added to the headings so they can be used within the anchor links.

Blocks

Blog posts have access to several blog-specific blocks to create more engaging and readable articles.

Image Block

If you want to show a photograph or image then use our custom image block. Do not use images for graphs or text-heavy content you expect the user to read. This poses accessibility issues for users on screen-readers and stops search engines from crawling this content.

You can optionally provide a caption, like below. Images with a caption will be given this ‘white box’ treatment. Images without a caption will just be full bleed.

Sizing

The block features controls for managing the aspect ratio if you want to enforce an aspect ratio. By default it will not enforce any aspect ratio and will just match the image’s intrinsic size, without expanding past the reading container.

Images inside blog posts are not typically shown at a size larger than 700 pixels wide. You should provide images that are ~1200px wide for higher DPI screens. You don’t need to worry about providing images at exactly the right size as the site will resize them for you to help with performance but try not to upload images larger than 2000 pixels in the longest dimension.

We recommend using landscape or square images only so that they don’t become larger than the screen’s height on desktop devices.

Pullquote

Pullquotes allow you to provide quotes with an emphasised treatment, pulling out key details from the regular copy. You should use this sparingly for important quotes and not as the default style for interviews that feature a lot of quotation.

You should always provide a citation when using a pullquote.

Blog Notice

The blog notice lets you highlight important information. This could be common pitfalls or errors the user may run into. You might also use it as an aside; a place to write some additional information outside of the main flow of the article.

The block has four styles: Info (the default), Warning, Error and Success. You can also customise the icon to be any in the Phosphor Icons set.

Code

If you’re discussing a technical element of web development/SEO and want to provide a code snippet then you can use the Code block. The Code block provides syntax highlighting to make the code more digestible as well as an easy ‘Copy to Clipboard’ button.

You can write the code in the sidebar, though to help manage indentation easier it’s recommended you copy & paste code from a code editor. Syntax highlighting can be offered for CSS, HTML, JS, PHP & TypeScript. You should always select the relevant language when using this block.

You should never write programming code in plain text but if you’re referencing a variable name, property or short snippet of code in the content of a paragraph then you can use the ‘Inline Code’ formatting option. You can find this by clicking the dropdown arrow next to the link option when highlighting text. See the below example:

To implement scroll-driven animation you can use the new animation-timeline property.

@keyframes scale-up {
  from {
    background-color: red;
    transform: scaleX(0);
  }
  to {
    background-color: darkred;
    transform: scaleX(1);
  }
}

#progressbar {
  animation: 2.5s linear forwards scale-up;
}

Future Additions

If you need any help with the formatting of blogs or any questions about this guide then get in touch with Kyle Cooper (kyle@webresultsdirect.com).

If your blog has specific needs for blocks that currently exist on the site but aren’t available on blogs then we can enable that. For example, you might want to use:

• Accordions
• Line & Bar Chart

If you have need for a new block then we can discuss development of that. This might include:

• Embedded Tools / Demos
• Author Call-outs