Get help on Discord

How Re-Produce Wordpress Short Code Functionality for Dynamic Content

22 replies
Last updated: May 4, 2020
I’m looking to re-produce something similar to the Wordpress short code functionality so my client can make page content dynamic (more on use case in 🧵). Should I use “Annotations” or a “Block” for this? I like how the Annotations are inline by default, which I’ll need. However, a “short code” block would be similar to the Gutenberg Short Code Block. However, I’ve never seen a block be placed inline with a paragraph (hence the name block).
AI Update

For creating WordPress-like shortcode functionality in Sanity, you should use inline blocks (also called inline objects) rather than annotations. Here's why:

Inline Blocks vs Annotations

Inline blocks are the better choice for shortcode-like functionality because:

  • They appear inline within text (like you want)
  • They can contain complex data structures and references
  • They're stored as actual objects in the children array alongside text spans
  • They can reference other documents or contain custom data

Annotations are designed for marking up text with metadata (like links, citations, or highlighting) and work differently - they use markDefs and apply marks to text spans.

How Inline Blocks Work

You add inline blocks by including an of property in your block type definition:

import { defineType } from 'sanity'

export default defineType({ 
  name: 'blockContent', 
  type: 'array', 
  of: [ 
    { 
      type: 'block', 
      of: [ 
        {
          name: 'productPrice', 
          type: 'object',
          fields: [
            {name: 'productId', type: 'string'},
            {name: 'region', type: 'string'}
          ]
        } 
      ] 
    } 
  ] 
})

This creates a button in the Portable Text Editor toolbar that lets editors insert your inline block directly into paragraphs - just like WordPress shortcodes!

The Output Structure

Inline blocks appear in the JSON output alongside text spans in the children array:

"children": [
  {
    "_type": "span",
    "text": "This product costs "
  },
  {
    "_type": "productPrice",
    "productId": "abc123",
    "region": "US"
  },
  {
    "_type": "span",
    "text": " in your region."
  }
]

Rendering on the Frontend

When you query and render this content, you'll need to resolve any references in your GROQ query and create custom serializers for your inline blocks in your Portable Text renderer (using @portabletext/react or similar).

The key difference from Gutenberg's shortcode block: Sanity's inline blocks can truly be inline within a paragraph, not just standalone blocks. This gives you the WordPress shortcode experience where dynamic content flows naturally within text.

For more details on implementation, check out the guide on adding inline blocks to Portable Text.

You can add custom objects to the block type too. Just add 
of: [{type: “aType”}]
to it. https://www.sanity.io/docs/block-type#of-d0f97ffa1dd9
Use Case: For each blog post category, there is a dynamic paragraph that gets displayed on each individual post page. This paragraph is different for each category and sources it’s dynamic data from the fields on the post page. Example:
Hello, welcome to my post called [postTitle]. It was created on [postPublishDate] by [postAuthor].
user Y
Yes, I have a lot of custom blocks already, that’s the “Block” solution I was referring to as one of my options. However, that will display the full width block in the editor which makes reading the inline content much harder, which was making me lean towards using “Annotations” (like external links are handled). Any down/upside to using one over the other in this case?
If I use an annotation, I would likely use the text being annotated as the reference value to the dynamic data. Re: use case above, 
postTitle
= 
props.postTitle
on the single blog post page.
Check the doc link ;) it’s not for the array, but for the 
block
. This should’ve been covered better in the documentation because it’s pretty powerful
Thanks
user Y
, not sure if there is something else I’m missing but I am implementing custom blocks already.I got this (almost) working using a custom annotation called “DynamicContent”. I pass the page props down to the 
BaseBlockContent
which uses a custom serializer. From there, I am matching the 
props.children
value with the dynamic page data (page props).
This is working for shallow props, but nested props are returning undefined. Know why?


const content = props.data[props.children]
This is custom inline blocks. 

{
	name: "content",
	type:"array",
	of: [
		{
			type: "block",
			of:[{type: "attributeSelection"}]
		}
	]
}
And then you could make a simple object, with predefined strings that you can use to target document fields in the frontend. 

{
	name:"attributeSelection",
	type:"object",
	fields:[{
		name:"attribute",
		type:"string",
		options:{
			list:[
			{title:"Publish date", value: "publishedAt"},
			//... and so on
			]
		}
	}]
}
Yup, I have all of that functioning, here is my custom block.
export default {
    title: 'Block Content',
    name: 'blockContent',
    type: 'array',
    of: [
      {
        title: 'Block',
        type: 'block',
        styles: [
          //...
        ],
        lists: [
          //...
        ],
        marks: {
          decorators: [
            //...
          ],
          annotations: [
            //...
            {
              title: 'Dynamic Content',
              name: 'dynamicContent',
              type: 'object',
            }
          ]
        }
      },
    //...
    ]
  }
My challenge is compiling the prop reference from another prop.
Example:
// "postTitle" works and returns "My Post Title successfully
{
  children: [
    0: "postTitle",
  ],
  data: {
    postTitle: "My Post Title",
    category: {
      title: "The Category Title",
    }
  }
}
However:

// "category.title" returns undefined
{
  children: [
    0: "category.title",
  ],
  data: {
    postTitle: "My Post Title",
    category: {
      title: "The Category Title",
    }
  }
}
For some reason, this code doesn’t work with nested objects…
const content = props.data[props.children]
I’m pretty sure that you want to take a closer look at my example :) isn’t this the thing you really want?
Not exactly. You are explicitly referencing another data set, in my case, the reference is dynamic based on the context (props) of the page. This is why I have to use the 
children
value and a reference to fetch the pages 
props
.
Ok. Let me take a closer look when I’m on my laptop
Use Case:A content section that will display on every blog post page but is unique for each category. Admin can manage this content at the category level, customize the content/paragraph but include dynamic data from the single blog post.


Example:On the single blog post page, you have content that reads:
“Welcome to my post
A Blog Post Title written by Knut Melvæ. Get all your latest news here.”
That post belongs to a category called “News” and in Sanity the field content for the News category is:
“Welcome to my post [TITLE] written by
[AUTHOR]. Get all your latest news here.”
So this isn't the authoring experience you're after
user T
?
And then you could do something like this: https://codesandbox.io/s/winter-sunset-rfebx?file=/src/App.js
Yes, that authoring experience would be fantastic. The key difference is that the dynamic content attribute reference is sourced from another record, not the current document. My body content would be on the Category record and it would be pulling in dynamic content from the blog post record under that category.
Your solution above is similar to what I’ve posted, however it only works on first level object references, you can’t reference anything nested in the props object. I’ve forked your CodeSandbox with an example trying to display a 
category.title
. https://codesandbox.io/s/jovial-hypatia-e7s3q?file=/src/App.js:340-389
I was able to get the nested attributes to work by using 
eval()
(I’d like feedback if that’s not wise and there are other alternatives). I’ve updated the CodeSandbox above with the new method and it demonstrates the functionality well.
user Y
Thanks for you help, one last point of clarify. In your latest screen recording, how did you configure the “Dynamic content” “Attribute” field reference? Is “Attribute” another document you created just to populate the dropdown and control those options?

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?