March 14, 2025· 6 min read

* Updated: 16.04.2024
Added V2 Button Types
Added Snippet Type

* Updated: 22.04.2025
Expanded Custom Shortcode to include a new type (static). (In Progress)
Added static shortcode as an example (In Progress)

Hello everyone!

I thought it would be much easier to draft this in preview mode so that all of you can see it in action, inspect the post for future reference, and have it readily available when using shortcodes.

As stated in previous Slack conversations, I have implemented a custom shortcode. Since it cannot be used as a standalone element without any options, I thought it would be helpful to provide an overview of the recently implemented custom shortcode.

From now on, to generate custom shortcodes that follow the same format and design as previous ones, you can use the shortcode.

You can specify two types of custom shortcodes: form (which includes an input field) and button.

Overview

To use a custom shortcode, you need to use the shortcode with specific options. Using it as a standalone element will not work because you need to specify parameters such as the body, URL, labels, etc.

I will now get a bit technical, but please refer to the section below for real examples and usage instructions, which may make it easier to understand.

Shortcode options

type => Can be either form , button, snippet or static
heading => Accepts HTML to highlight certain keywords and/or place text on a new line / Accepts plain text when using useNewDesign or type snippet
body => Plain text
placeholder => Plain text, specifies the text within the input field when nothing has been typed, available only for the form type.
cta_label => Plain text, specifies the text within the button/CTA.
url => A plain URL (not formatted/linked within ButterCMS), which is the destination users should be redirected to.
darkMode => Boolean that determines if the shortcode should use the dark or light version. Only available for shortcodes that have type button and useNewDesign properties present. (optional)
useNewDesign => Available only for button type. Determines whether a new version of CTA should be used or not. (optional)
title => Available only for snippet type.

URL Handling

Regarding the URL, you can add UTM tags, for example: https://example.com/?utm_medium=referral...

For the form type, when using a URL, the {value} placeholder should be included. The {value} will be replaced with the user-entered input within the shortcode. For example, if a user types "semrush" in the CTA input field, the {value} in the URL will be replaced with the encoded user input:

https://www.google.com/search?q={value}&utm_medium=referral → https://www.google.com/search?q=semrush&utm_medium=referral

Usage

To place a button CTA within a blog post, use the following format:
``

To place a form CTA within a blog post, use the following format:
``

To place a snippet CTA within a blog post, use the following format:
``

To place a static CTA within a blog post, use the following format:
``

Note: I intentionally placed a space after cta: to prevent it from being parsed.

When using <html_text>, you can apply formatting such as:

<span>TEXT</span> to make TEXT orange.
<br /> to force text onto a new line.

Important note: When placing a URL, it should not be linked within ButterCMS.

Examples

Button type:

Form type:

Static type:

V2 Button Examples:

Feature Snippet Boxes:

Calculator shortcodes

Note: I intentionally placed a space after cal: to prevent it from being parsed.

Usage: [cal: comp_keywords]

Result:

[cal:comp_keywords]

Usage: [cal: traffic]

Result:

[cal:traffic]

Usage: [cal: aio]

Result:

[cal:aio]

Usage: [cal: freshness]

Result:

[cal:freshness]

Usage: [cal: rank_time]

Result:

[cal:rank_time]

Usage: [cal: email_roi]

Result:

[cal:email_roi]

Usage: [cal: content_opp]

Result:

[cal:content_opp]

Test

Preselected Keyword Rank Checker:

[incontent-related-articles:keyword-rank-checker]

Default (SEO category attached to this blog):

[incontent-related-articles]

All 3 Preselected (Keyword Rank Checker, Top Google Searches and E-commerce APIs)

[incontent-related-articles:keyword-rank-checker,top-google-searches,e-commerce-apis]

Preselected Keyword Rank Checker and Top Google Searches:

[incontent-related-articles:keyword-rank-checker,top-google-searches]

Default (SEO category attached to this blog + preselected the same post - content-calendar-planning /checking for duplication):

[incontent-related-articles:content-calendar-planning]

Test - site audit

Test - topics shortcodes

[list=topic number=5 category=health]

[list=product number=5 category=beauty]

[list=startup number=5 category=ai]

Here's a full list of available categories.

Shortcodes (CTA)

Usage:

Result:

Usage:

Result:

Usage:

Result:

Usage:

Result:

Usage:

Result:

Usage:

Result:

Usage:

Result:

Usage:

Result: