Shortcode Markup: An Implementation Guide

Categories
Copywriting

Learn what shortcode markup is and how your team can start using it.

As budgets tighten and AI looms, marketing teams are under pressure to keep operating costs to a minimum while outputting work faster than ever. There are thousands of ways to build more agile, efficient departments, but, in this article, we’ll focus on removing friction – specifically, the friction between copy and design teams.

Rendering copy into a usable design can be hard, especially if the copy doc is raw (that is, a Microsoft Word or Google Doc page just filled with unformatted text). Design teams are forced to spend time thinking about what goes where and how the copywriter intended their content to look and flow.

At first, this point of friction seems insignificant. Cumulatively, though, it starts to have an effect. When friction occurs across hundreds of tasks, it costs significant time and money and can also compromise quality.

My solution: design enablement via shortcode markup. I’ve been testing these two concepts in field environments for the past year or so, and, almost always, they translate into better design results and better approver feedback without any extra project costs.

Shortcode markup has become the default Chevron Editing style for technical copy and content tasks. With this guide, you can make it part of your team’s workflows too.

What Is Design Enablement?

Design enablement is a copywriting and content creation methodology that helps graphic and UX designers do their best work. Too often, copy is handed directly to designers as a Microsoft Word document in a format that looks something like this:

poor design enablement example

Under design enablement principles, this deliverable is unacceptably ambiguous – the recipient designer must essentially guess the intentions of the copywriter. Instead, copywriters and content creators need to effectively communicate their intentions, allowing designers to focus on creating exceptional web pages, apps, brochures, and infographics.

What Is Shortcode Markup?

Shortcode markup is a copywriting style that draws inspiration from WordPress’s shortcode system, which involves dynamically replacing bracketed macros with content using PHP. Shortcode markup embraces a similar principle – bracketed content serves as a stand-in for design ideas, allowing copywriters to quickly and easily draft functional layouts.

Here’s an example:

business success consulting

In the above instance, there are two shortcode markup elements: ‘[hero header]’ and ‘[CTA]’. ‘[hero header]’ is a trammelled element – it has an opening and closing shortcode, which indicates that the content between them is included within the shortcode (more on how this works shortly).

Why Do Marketing Teams Need Shortcode Markup?

In most go-live flows I see, there is a gap between the copywriter’s intentions and the understanding of those intentions parsed by the designers.

Ideally, copywriters and designers should collaborate on pieces, working together in synergy to produce a refined, conceptually sound deliverable that everyone loves. In reality, though, timelines and team structures mean this rarely happens.

Instead, the scenario normally goes one of two ways:

  1. The copywriter submits a raw MS Word/Google Docs file with minimal formatting. Cue guessing games from the design team.
  2. The copywriter practices their design skills, spending time rendering the copy via wireframes/mockups.

The first option has multiple problems. One, both approvers and designers have trouble visualising what the end deliverable should look like. This means reviews are less effective and designs struggle to incorporate the copy in the right way.

Two, designers spend time and cognition attempting to understand the copywriter’s intentions. This leads to higher project costs and a heavier cognitive load for your design team.

Three, the copywriter may not have actually visualised the copy in its final form, which can result in copy that is not fit for purpose – too much text on brochure pages, for example, or a web page that’s missing critical elements.

The second option (letting the copywriter mock up their work) also has issues. The first problem is that you’re essentially paying the copywriter twice over – once for the words and once for putting those words into a rudimentary design (which possibly won’t be to a professional standard). This leads to significant increases in timelines and project costs.

Secondly, if your copywriter does submit their deliverables in a PDF/image/formatted Word doc, approvers subsequently struggle to make changes and separate the copy from the design. Poor design from a copywriter can make their words seem less suitable than they actually are, implementing edits takes the copywriter more time, and no editor likes trying to mark up changes in Adobe Acrobat.

Shortcode markup offers a bridge between these two scenarios. With a set system of shortcode elements in place, everyone involved in the project can instantly understand the intended layout of the copy. For copywriters, shortcode elements can be easily added to MS Word or Google Docs – there’s no additional software or time required.

The result: designers don’t have to guess at layouts, copywriting costs less and ships faster, and approvers can make recommendations with full context.

How Shortcode Markup Works

Shortcode markup pairs built-in word processor styles with shortcode elements – bracketed terms that act as signifiers for design concepts.

Headings are indicated using the H (H1, H2, H3, et cetera) styles in MS Word or Google Docs. Body text is formatted normally, with a font size of 11 or 12 points, a sans serif font like Calibri, and an easy-to-read line spacing (I recommend multiple line spacing at 1.08 points with a 12-point break after each carriage return).

This consistency makes it easy for everyone involved to understand exactly which text is a heading instead of, for example, bolded body text. If you’re copying content directly into a CMS like WordPress, headings will also copy over into rich text editors, which reduces the workload for your web developers.

Design concepts (for example, brochure pages, hero headers on websites, images, or HTML accordions) are all indicated using shortcode elements. These will be replaced during the design or upload stage (depending on your process) with the concepts that they represent.

Shortcode elements are either self-contained or trammelled. Self-contained elements are wholly replaced with the respective design concept – for example, ‘[image]’ would simply be replaced with an image of the designer’s choice.

self-contained shortcode markup

Trammelled elements are slightly more complex. They feature an opening shortcode and a closing shortcode, the latter of which is indicated by a forward slash behind its first bracket; any content in between the two shortcodes will be included within the element.

trammelled shortcode

It’s important to understand that shortcode markup exists to clarify copywriter intent, not inform design per se. As such, the diversity of shortcodes is deliberately limited. For example, using ‘[image]’ instead of ‘[photo]’ leaves the choice up of whether the image should be a photo, a graphic, or an illustration up to the designer.

If additional instructions or details are required beyond what shortcode markup enables, add them using in-document review comments.

Implementing Shortcode Markup Within Teams

Shortcode markup is purpose-built for easy implementation. Your copywriters should have little, if any, trouble understanding how it works, and your designers and web developers are likely already familiar with the concept of WordPress shortcodes.

Firstly, put aside half an hour for your team members to read this blog. Once they understand and identify with the issues we’ve discussed here, they’ll be more willing to try something new.

Secondly, add this URL (https://chevronediting.com.au/shortcode-markup/) to your team’s Slack, SharePoint, or Coda instance, preferably in the same place as your brand voice and textual style guides. Make sure you add a section on shortcode markup to your style guide too.

Thirdly, collect feedback at regular intervals. Expect initial pushback (new copywriting styles are rarely greeted with joy) followed by total adoption. If shortcode markup doesn’t work for your people, though, don’t force it – I’ve tested it across many client scenarios, but it may not be the right fit for you, and that’s fine.

Fourthly, whether implementation succeeds or fails, I’d love to hear how it went. I’ve been testing shortcode markup for about a year, but I expect it will keep evolving over time, and the more data that informs that evolution, the better the end result will be.

Shortcode Markup Guide

title

Use this style for document titles (not copy). This makes it easier for readers to differentiate between the words that need to be in the deliverable and a descriptive document title.

Example


Pages and Sections

form

A trammelled shortcode that indicates a page of some kind.

section

A trammelled shortcode that indicates a visually distinct section of some kind.

Example in Word

example of the section shortcode in microsoft word

Example in the Wild

example of the section shortcode in the wild

title

A trammelled shortcode that indicates the hero header on a web page.

table

Tables are used to indicate the adjacent display of content rather than spreadsheet-style tables. For example, two side-by-side cells on a web page would generally indicate grid content.

If the intention is for the table to be rendered as an actual spreadsheet-style table, this should be specified with a comment.

Page Content

title

Use H styles to indicate headings. They should be semantically correct – H1s come first, H2s sit under them, followed by H3s under them, and so on.

title

Use unordered and ordered lists as per normal.

title

A trammelled shortcode that indicates a visually distinct section where a quote or pull-out (not a heading) is accentuated.

Example in Word

Example in the Wild

cta

A shortcode that indicates a call-to-action button (insert the button text after the hyphen).

Example in Word

An example of a CTA button in Microsoft Word.

Example in the Wild

An example of a CTA button in the wild.

cta

A shortcode that indicates a call-to-action link rather than a button (insert the link text after the hyphen).

Secondary call-to-action links are useful for highlighting alternate actions to the main page objective.

Example in Word

An example of a secondary CTA in Microsoft Word.

Example in the Wild

An example of a secondary CTA in the wild.

image

A self-contained shortcode that indicates an image of some kind, such as a photo, graphic, or illustration.

caption

A trammelled shortcode that indicates a caption for an image or video.

The Caption shortcode should be used directly after the Image or Video shortcodes to which it is appended.

icon

A self-contained shortcode that indicates an icon of some kind, typically either as an icon font like Font Awesome or as an SVG.

video

A self-contained shortcode that indicates a video embedded as an HTML object.

blockquote

A trammelled shortcode that indicates a quotation rendered as a visually distinct block.

infographic

A trammelled shortcode that indicates an infographic – that is, a standalone image that contains text and graphics and serves to convey information.

Within the infographic, other shortcode elements, such as tables, images, and text, can be used.

QR code

A self-contained shortcode that indicates a QR code.

infographic

A shortcode that indicates a missing number that requires filling – such as a statistic – before going live.

embed

A self-contained shortcode used to embed inline frames (iframes), plugins, and other objects on web pages.

Insert a description of the embedded object after the hyphen, such as [ embed – Google Maps Embed API ].

content

A self-contained shortcode used to indicate missing content that will be input during a later round of writing or editing.

Add discursive text after the dash to indicate the content in question.

overlap

A trammelled shortcode that indicates the contained content should partially overlap adjacent content.

The Overlap shortcode should only be used adjacent to Hero Header, Hero Text, or Section shortcodes.

After the hyphen, put ‘up’, ‘down’, ‘left’ or ‘right’ to indicate the direction of overlap.

Interactive Objects

slider

A trammelled shortcode that indicates an HTML carousel or slideshow of some kind.

The Slide shortcode must be used to indicate the content of each carousel slide.

text swap

A trammelled shortcode that indicates a HTML text swap (where letters, words or phrases rotate automatically on a carousel).

The Slide shortcode must be used to indicate the content of each carousel slide.

slide

A trammelled shortcode that indicates the content of a slide.

The Slide shortcode can be used with the Slider shortcode or the Text Swap shortcode.

tab

A trammelled shortcode that is used for HTML tabs.

The ‘X’ should be replaced by the tab number (1, 2, etc.). Typically, tabs are numbered according to the order in which they appear on the page.

Tab shortcodes must be used in concert with tab content shortcodes.

tab content

A trammelled shortcode that is used for the content of HTML tabs (that is, the content that appears when a tab is clicked).

The ‘X’ should be replaced by the corresponding tab number.

Tab content shortcodes must be used in concert with tab shortcodes.

accordion

A trammelled shortcode used to indicate an HTML accordion.

Insert the button text (the text that is visible before the accordion is expanded) after the hyphen.

timeline

A trammelled shortcode used to indicate an HTML timeline.

After the hyphen, input either ‘horizontal’ or ‘vertical’ to indicate whether the timeline runs from top to bottom or left to right.

A timeline shortcode must be used with timeline content shortcodes.

timeline content

A trammelled shortcode used to indicate content that is part of an HTML timeline.

If the timeline is horizontal, input either ‘top’ or ‘bottom’ before ‘timeline content’ to indicate where that section of content appears in relation to the timeline.

If the timeline is vertical, input either ‘left’ or ‘right’ before ‘timeline content’ to indicate where that section of content appears in relation to the timeline.

A timeline content shortcode must be used with a timeline shortcode.

Forms

form

A trammelled shortcode that indicates a web form of some kind.

form results

A trammelled shortcode that indicates the on-page content that appears when a form is submitted.

The Form Result shortcode should appear directly after the Form shortcode to which it relates.

output

A self-contained shortcode that indicates content within a Form Result shortcode dependent on information submitted in the form.

part

A trammelled shortcode that indicates a part of a multi-part form.

The ‘X’ should be replaced by the part’s number – for example, ‘[part 1]’.

Parts can generally only be used inside a form.

field

A shortcode that indicates a field on a form. The type of field can be indicated by adding the input type at the start of the shortcode.

The field’s label can be added after the hyphen; the field’s default value can be added after the label (separated by a comma). Indicate a required field by placing an asterisk after the ‘field’ but before the hyphen (e.g. [email field* – Email]).

Available self-contained Fields include:

  • [text field – ]
  • [expanded text field – ]
  • [file upload field – ]
  • [email field – ]
  • [phone field – ]
  • [checkbox field – ]
  • [search field – ]
  • [numbers field – ]
  • [number spinner field – ]

Available trammelled Fields include the below. Options can be listed as ordered or unordered lists, depending on your preference.

  • [radio field – ] [/radio field]
  • [dropdown field – ] [/dropdown field]
  • [range slider field – ] [/range slider field] (listed options for the Range Slider Field will be displayed left to right in the rendered field)

Fields can normally only be used inside Form, Form Parts, or Filter shortcodes.

filter

A trammelled shortcode that indicates a HTML filter.

Use Field and CTA shortcodes within the Filter shortcode.

Use the Filter Content shortcode to designate the content affected by the filter.

filter content

A trammelled shortcode that must be used with the Filter shortcode.

Use the Filter Content shortcode to designate the content affected by the filter.

More elements coming soon.

Changelogs provide transparency into when and why we make changes to certain articles. We do not log minor stylistic changes or grammatical fixes.

22 December 2023

  • Caption, Overlap, Phone Field, and Number Spinner Field shortcodes added.
  • Visual examples added for Section shortcode.

3 July 2023

  • Default text option added to Field shortcode.
  • Field shortcodes separated into self-contained and trammelled.
  • Required field option added to Field shortcode.
  • Visual examples added for CTA and Soft CTA shortcodes.
  • Numbers Field, Content, Slider, Text Swap, QR Code, Filter, and Filter Content shortcodes added.
  • Slider shortcode changed to a trammelled shortcode.

By Duncan Croker

Duncan is a copywriter with a background in editing and storytelling. He loves collaborating with brands big and small, and thrives on the challenges of hard marketing.