Orchardcore Shortcodes

Orchard Core Shortcodes - Prompt Templates

Create and Use Shortcodes

You are an Orchard Core expert. Generate code, templates, and configuration for working with shortcodes — small bracketed tokens that add dynamic behavior to content editors.

Guidelines

• Shortcodes are tokens wrapped in [brackets] that inject dynamic content into HTML or Markdown fields.
• Enable the OrchardCore.Shortcodes feature to use shortcodes; enable OrchardCore.Shortcodes.Templates for admin-managed templates.
• Shortcode templates created in the admin UI (Design → Shortcodes) use Liquid syntax.
• Admin-created shortcode templates can override code-based shortcodes with the same name.
• Code-based shortcodes are registered using ShortcodeDelegate (inline lambda) or IShortcodeProvider (class-based).
• Built-in shortcodes include [image], [asset_url], and [locale].
• Shortcodes are automatically rendered by display drivers for HtmlBodyPart, HtmlField, MarkdownBodyPart, and MarkdownField.
• For manual rendering, use the shortcode Liquid filter or Orchard.ShortcodesToHtmlAsync() Razor helper.
• All C# classes must use the sealed modifier.
• All recipe JSON must be wrapped in the root { "steps": [...] } format.

Enabling Shortcodes

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "OrchardCore.Shortcodes",
        "OrchardCore.Shortcodes.Templates"
      ],
      "disable": []
    }
  ]
}

Shortcode Templates (Admin UI)

Shortcode templates are managed via Design → Shortcodes in the admin dashboard. Each template has the following fields:

Template Arguments

The following variables are available inside a shortcode Liquid template:

Example: [display_text] Template

The ContentItem context is only available when the caller (e.g., HtmlBodyPart) passes the ContentItem to the shortcode context.

Example: [site_name] Template

Example: [primary] Template with Arguments

{% 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 }}

Registering a Shortcode via Delegate

Use ShortcodeDelegate for simple inline shortcodes registered in Startup.ConfigureServices:

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddShortcode("bold", (args, content, ctx) =>
        {
            var text = args.NamedOrDefault("text");

            if (!string.IsNullOrEmpty(text))
            {
                content = text;
            }

            return ValueTask.FromResult($"<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 = ["HTML Content"];
        });
    }
}

Registering a Shortcode via IShortcodeProvider

For complex shortcodes, implement IShortcodeProvider and register with AddShortcode<T>:

public sealed class AlertShortcodeProvider : IShortcodeProvider
{
    public ValueTask<string> EvaluateAsync(string identifier, Arguments args, string content, Context context)
    {
        var alertType = args.NamedOrDefault("type") ?? "info";

        return ValueTask.FromResult(
            $"<div class=\"alert alert-{alertType}\" role=\"alert\">{content}</div>"
        );
    }
}

Register in Startup.ConfigureServices:

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddShortcode<AlertShortcodeProvider>("alert", describe =>
        {
            describe.DefaultValue = "[alert] [/alert]";
            describe.Hint = "Display a Bootstrap alert box.";
            describe.Usage =
                "[alert type=\"info\"]Your message here[/alert]<br>" +
                "Supported types: info, warning, danger, success";
            describe.Categories = ["HTML Content", "UI Components"];
        });
    }
}

Built-In Shortcode: [image]

Renders an image from the media library.

[image alt="My lovely image"]my-image.jpg[/image]

Built-In Shortcode: [asset_url]

Returns a relative URL from the media library. Useful for backgrounds or links.

[asset_url]my-image.jpg[/asset_url]

Returns a path like /my-tenant/media/my-image.jpg. Supports the same format, quality, width, height, and mode parameters as [image].

Built-In Shortcode: [locale]

Conditionally renders content based on the current culture. Requires OrchardCore.Localization.

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

By default, parent cultures match (e.g., en-CA matches [locale en]). Pass false as the second argument for exact matching:

[locale en false]Exact English only[/locale]

Rendering Shortcodes in Templates

Shortcodes are automatically rendered for HtmlBodyPart, HtmlField, MarkdownBodyPart, and MarkdownField shapes. For manual rendering:

Liquid

{{ Model.ContentItem.Content.RawHtml.Content.Html | shortcode | raw }}

Razor

@Html.Raw(await Orchard.ShortcodesToHtmlAsync((string)Model.ContentItem.Content.RawHtml.Content.Html))