Orchardcore Theming

Orchard Core Theming

Use this skill for Orchard Core theming tasks including theme creation, shape overrides, template discovery, content rendering, placement rules, and asset management.

How to Use

• Task match: Scan the Tasks list below. If the request matches, go directly to the referenced files.
• Exploration: Use the section cues to pick a reference, then choose the relevant detail.
• Determine Razor vs Liquid early. Check the active theme for .cshtml (Razor) or .liquid files. If unclear, default to Liquid and confirm with the user.
• Open only the necessary reference files; prefer examples and ready-to-copy patterns.

Evidence Rules

• Prefer repo evidence over assumptions: check the active theme, base theme, placement.json, and existing templates.
• Confirm unknown part/field properties in ContentDefinition.json or the database.
• Ask for missing identifiers (content type, part name, field name, display type) instead of inventing them.
• Do not invent recipe steps or feature IDs; consult the recipes skill for valid steps.

Guidelines

• Theme names should be PascalCase and may be prefixed with the organization name (e.g., CrestApps.MyTheme).
• Themes must have a Manifest.cs declaring the theme and its base theme (if any).
• Prefer shapes over MVC partials for UI composition.
• Views/Layout.cshtml is treated as the site layout automatically; do not set Layout = null inside it.
• Override base theme views in the child theme rather than editing the base theme.
• Use {% render_section "SectionName" %} in Liquid layouts to render named sections.
• Asset pipelines can be managed through wwwroot/ and resource manifests.
• The TheAdmin theme is used for the admin panel and can be extended.

Reference Cues

Use these cues to decide which reference file to open:

• Use references/theming-examples.md for end-to-end theme creation examples (manifests, layouts, shape overrides).
• Use references/shape-alternates.md to find shape names, alternates, and naming rules for template overrides.
• Use references/placement-rules.md for placement.json patterns, filters, differentiators, and editor grouping.
• Use references/shape-workflow.md for a step-by-step checklist to build or override a shape safely.
• Use references/assets-resources.md for resource manifests, requiring scripts/styles, and built-in Orchard Core resources.

Tasks

• Create a new theme from scratch.
• Override a content item shape template.
• Find shape alternates and placement rules.
• Add or override placement rules in placement.json.
• Add scripts/styles and include them in the layout.
• Create or customize the admin theme.
• Render BagPart/FlowPart/ListPart items in templates.
• Update a shape after adding fields.
• Work on theme structure or layout.
• Determine template language (Razor vs Liquid).

Create a Theme

Manifest Pattern

using OrchardCore.DisplayManagement.Manifest;

[assembly: Theme(
    Name = "{{ThemeName}}",
    Author = "{{Author}}",
    Website = "{{Website}}",
    Version = "1.0.0",
    Description = "{{Description}}",
    BaseTheme = "{{BaseTheme}}"
)]

Project File Pattern

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="OrchardCore.DisplayManagement" Version="3.*" />
    <PackageReference Include="OrchardCore.Theme.Targets" Version="3.*" />
  </ItemGroup>

</Project>

Theme Folder Structure

MyTheme/
├── Manifest.cs
├── MyTheme.csproj
├── Views/
│   ├── Layout.liquid (or Layout.cshtml)
│   ├── _ViewImports.cshtml
│   └── Items/
│       └── Content-BlogPost.liquid
├── wwwroot/
│   ├── css/
│   │   └── site.css
│   └── js/
│       └── site.js
├── placement.json (optional)
└── ResourceManagementOptionsConfiguration.cs (optional)

_ViewImports for Razor Themes

If a theme uses Razor, _ViewImports.cshtml should exist with at least:

@inherits OrchardCore.DisplayManagement.Razor.RazorPage<TModel>

If it's missing, it can cause build errors.

Liquid Layout Template

<!DOCTYPE html>
<html lang="{{ Culture.Name }}">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ Model.Title }} - {{ Site.SiteName }}</title>
    {% resources type: "HeadMeta" %}
    {% resources type: "HeadLink" %}
    {% style src: "~/{{ThemeName}}/css/site.css" %}
    {% resources type: "Stylesheet" %}
</head>
<body>
    {% zone "Header" %}

    <main role="main" class="container">
        {% zone "BeforeContent" %}
        {% zone "Content" %}
        {% zone "AfterContent" %}
    </main>

    {% zone "Footer" %}

    {% resources type: "FootScript" %}
    {% script src: "~/{{ThemeName}}/js/site.js" at: "Foot" %}
</body>
</html>

Razor Layout Template

@inject OrchardCore.IOrchardHelper Orchard

<!DOCTYPE html>
<html lang="@Orchard.CultureName()">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>@RenderTitleSegments(Site.SiteName)</title>
    @await RenderSectionAsync("HeadMeta", required: false)
    <link rel="stylesheet" href="~/{{ThemeName}}/css/site.css" />
    @RenderSection("Styles", required: false)
</head>
<body>
    @await DisplayAsync(ThemeLayout.Header)

    <main role="main" class="container">
        @await DisplayAsync(ThemeLayout.Content)
    </main>

    @await DisplayAsync(ThemeLayout.Footer)

    <script src="~/{{ThemeName}}/js/site.js"></script>
    @RenderSection("Scripts", required: false)
</body>
</html>

Shape Templates

Override shape rendering by creating templates in the Views/ folder:

• Content.liquid — Default content item display.
• Content-BlogPost.liquid — Content display for BlogPost type.
• Content-BlogPost.Summary.liquid — Summary display mode for BlogPost type.
• Widget.liquid — Default widget wrapper.
• MenuItem.liquid — Menu item rendering.

File naming convention: __ in shape type maps to - in file names; _DisplayType maps to .DisplayType suffix.

Resource Manifest

using Microsoft.Extensions.Options;
using OrchardCore.ResourceManagement;

public sealed class ResourceManagementOptionsConfiguration : IConfigureOptions<ResourceManagementOptions>
{
    private static readonly ResourceManifest _manifest = CreateManifest();

    public void Configure(ResourceManagementOptions options)
    {
        options.ResourceManifests.Add(_manifest);
    }

    private static ResourceManifest CreateManifest()
    {
        var manifest = new ResourceManifest();

        manifest
            .DefineStyle("{{ThemeName}}")
            .SetUrl("~/{{ThemeName}}/css/site.min.css", "~/{{ThemeName}}/css/site.css");

        manifest
            .DefineScript("{{ThemeName}}")
            .SetUrl("~/{{ThemeName}}/js/site.min.js", "~/{{ThemeName}}/js/site.js")
            .SetPosition(ResourcePosition.Foot);

        return manifest;
    }
}

Register the configuration from the theme or module startup:

using Microsoft.Extensions.DependencyInjection;
using OrchardCore.Modules;

public sealed class Startup : StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddResourceConfiguration<ResourceManagementOptionsConfiguration>();
    }
}

Zones

Common zones used in Orchard Core themes:

Zone Alternates

Zone shapes support alternates for per-zone template overrides:

• Zone__ZoneName → file Zone-Footer.cshtml (or .liquid)