Skip to content

Shortcodes (OrchardCore.Shortcodes)

Adds Shortcode capabilities.

Shortcodes are small pieces of code wrapped into [brackets] that can add some behavior to content editors, like embedding media files.

Shortcodes can be implemented by enabling the Shortcode Templates feature or through code.

Shortcode Templates

Shortcode templates with Liquid are created through the Design -> Shortcodes menu.

Shortcode templates are designed to be able to override a code based Shortcode of the same name.

Parameter Description
Name The name of your Shortcode, without brackets.
Hint The hint to display for your Shortcode.
Usage An html string to describe the usage and arguments for your Shortcode.
Categories The categories your Shortcode falls under.
Return Shortcode The Shortcode value to return from the Shortcode picker when selected. Defaults to Name.
Content The Liquid template for your Shortcode.

Template Arguments

Parameter Description
Args The arguments provided the user, if any.
Content The inner content provided by the user, if any.
Context The context made available to the Shortcode from the caller, e.g. an HtmlBodyPart.

Example Shortcode Templates :


Parameter Value
Name display_text
Hint Returns the display text of the content item.
Usage [display_text]
Content {{ Context.ContentItem.DisplayText }}
{{ More }}


The ContentItem Context is only available when the caller, i.e. an HtmlBodyPart, has passed the ContentItem value to the Context.


Parameter Value
Name site_name
Hint Returns the site name.
Usage [site_name]
Content {{ Site.SiteName }}


Parameter Value
Name primary
Hint Formats text in the themes primary color.
Usage [primary text]<br<[primary]text[/primary]
Content {% capture output %}
{% if Args.Text != nil %}
<span class="text-primary">{{Args.Text}}</span>
{% else %}
<span class="text-primary">{{Content}}</span>
{% endif %}
{% endcapture %}
{{ output | sanitize | raw }}

Shortcodes via code

Shortcode Delegate

Shortcodes can be registered in code via a ShortcodeDelegate using the AddShortcode extension method.

Parameter Type Description
Name string The name of the Shortcode.
Shortcode ShortcodeDelegate The Shortcode Delegate.
Describe Action<ShortcodeOption> Optionally a Description of the Shortcode.

In this example, we register a [bold] Shortcode Delegate and describe the Shortcode.

services.AddShortcode("bold", (args, content, ctx) => {
    var text = args.NamedOrDefault("text");
    if (!String.IsNullOrEmpty(text))
        content = text;

    return new ValueTask<string>($"<b>{content}</b>");
}, describe => {
    describe.DefaultValue = "[bold text-here]";
    describe.Hint = "Add bold formatting with a shortcode.";
    describe.Usage = "[bold 'your bold content here']";
    describe.Categories = new string[] { "HTML Content" };


Shortcodes may also be used by implementing the IShortcodeProvider interface and registered with the AddShortcode extension method.

In this example we register an ImageShortcodeProvider as [image] and describe the Shortcode.

services.AddShortcode<ImageShortcodeProvider>("image", describe => {
    describe.DefaultValue = "[image] [/image]";
    describe.Hint = "Add a image from the media library.";
    describe.Usage = 
    <td>width, height, mode</td>
    <td>class, alt</td>
    describe.Categories = new string[] { "HTML Content", "Media" };


When upgrading from version 1.0.0-rc2-13450 you may need to re-enable the Shortcodes feature, through Configuration -> Features

The Shortcode Templates feature is only available from the Preview Feed

Available Shortcodes


The locale shortcode allows you to conditionally render content in the specified language. Output is based on the current thread culture. This shortcode is accessible when the OrchardCore.Localization module is enabled.


[locale en]English Text[/locale][locale fr]French Text[/locale]

By default, the shortcode will render the content if the current locale is a parent of the specified language. For example, if the current locale is en-CA and you specified this shortcode: [locale en]English Text[/locale] The output will be English Text. You can disable this behavior by passing false as the second argument of the shortcode. [locale en false]English Text[/locale] would render nothing if the current culture is not exactly en.

Rendering Shortcodes

Shortcodes are automatically rendered when using a Shape produced by a display driver that supports Shortcodes.

  • HtmlBodyPart
  • HtmlField
  • MarkdownBodyPart
  • MarkdownField
{{ Model.Content.HtmlBodyPart | shape_render }}
@await DisplayAsync(Model.Content.HtmlBodyPart)

Shortcodes can also be rendered via a liquid filter or html helper

{{ Model.ContentItem.Content.RawHtml.Content.Html | shortcode | raw }}
@Html.Raw(@await Orchard.ShortcodesToHtmlAsync((string)Model.ContentItem.Content.RawHtml.Content.Html))


Last update: May 19, 2021
Authors: Dean Marcussen, Jasmin Savard