Skip to content

Content Management

Content is built from pages and extensions. A page (/p/{seoName}) has a layout with named slots, and each slot holds an ordered list of extensions (content blocks). Collections, products and stereotypes are filled with extensions the same way. Everything here can also be done by an AI agent through the MCP pages, menus, media, extensions and stereotypes tools; see MCP & OAuth2.

Pages

Admin → Site → Pages (/admin/site/pages). The edit screen has three panels:

  • Info: name, seoName (the URL slug), description, parent pages, canonical path, meta title / description / keywords, Disabled, Exclude from sitemap and Exclude from site search. A disabled page returns 404. A draft (see below) shows a Draft note here instead of the switch.
  • Data: layout template (Standard, Empty Page, 9 by 3, 3 by 9; see page layouts) and stereotype.
  • Extensions: each slot with its extensions and an Add extension to this slot button, which opens a categorised picker. Each extension has its own settings form. Order within a slot is the numeric displayPriority setting (lower first, default 1000); there is no drag-and-drop.

Drafts. A draft is a page that has never been published and is waiting for someone to approve it. It is always also disabled, so it stays off the storefront, search, the sitemap and blog lists. The pages list shows it as Draft (a page taken offline shows Disabled), and the edit screen has a Publish button instead of the Hide this page switch: saving the form never makes a draft live. Publishing makes the page live and, on its first publish, records the approving user (publishedBy) and the time (publishedDate). The time is also written to createdDate, which blogs use to date and order posts, so a post is dated when it is approved. The exception is a draft that was given its own post date (draftPostDate, set through PageService.setDraftPostDate; the MCP managePages tool does this when a draft is created or updated with a publishedDate), for a post about something that happened earlier, such as a callout report written up days later: the draft shows that date in its preview and keeps it when published, while publishedDate still records when it was approved. The admin post editor doesn't set draftPostDate, so a draft published from there is dated when it is approved; change the date afterwards. Drafts are created through PageService.createDraft; publishing goes through PageService.publish. The blog post editor keeps its Draft switch: turning it off on a never-published draft publishes it the same way. Drafts can also come from a change request: its writer saves the draft page (marked with the request's changeRequestId) and the request's Approve and publish button publishes it the same way.

Previews. A draft or disabled page or blog post has Preview and Copy preview link buttons in its editor. The link, /preview/{token}, shows the page exactly as it will look once published, under a "Preview: this page isn't published yet" banner (Nova-family themes), to anyone who has it, for 14 days. It shows the page as it is when opened, so it keeps working while the draft is edited. Previews are sent with noindex, no-store, no-referrer and X-Frame-Options: SAMEORIGIN (so the admin's change request screen can show the draft in a frame on the same host), and don't count as page views. Links are signed with a per-site secret (page-preview-signing-key, group content-config, provisioned on first use), so a link only works on its own site; clearing the key revokes every link already shared. PagePreviewTokenService signs and checks them; PageController serves them.

Global pages (/admin/site/globalPages) are platform-provided pages that can be cloned into the site. A CMS page with seoName 4xx or 5xx replaces the built-in error page.

Inline editing. An admin can add ?inlineEdit to a storefront URL to edit jsonComponent blocks in place, in a side panel with a live preview. The storefront's floating Admin button links to it (Edit this page), and its Stop editing this page leaves it. Pointing at a component's section in the side panel outlines that component on the page and names its type; clicking into one of its fields also scrolls it into view. The outline follows what the page shows, so a component added in the panel is only outlined once it has been previewed.

Content blocks

Extension What it is
htmlFragment Rich text / HTML, edited with a WYSIWYG editor (Summernote)
markdownFragment Markdown (CommonMark + tables), edited with a Markdown editor that only ever saves Markdown, optional "blog mode" styling and template variables for the user and order. Products, collections and pages are referred to by reference, so their names, prices and addresses stay current
jsonComponent Composed layouts: containers, rows, headings, text, images, buttons, tabs, accordions, carousels, product grids/carousels bound to a collection, merchandising node, trending or recently viewed. See JSON Components
hero Banner with six presets: centered, split image, video background, gradient, minimal, background effect. Every preset can also show an eyebrow, a second button and a stats strip; see Extension System. Centered and gradient can fade between several background photos (slideshow)
callToAction A call to action edited as a form (eyebrow, heading, text, figure, up to two buttons) in one of four styles: a full-width band, a strip, a sidebar panel or a single stat. See Extension System
storeLocator "Find a store": the shop's first few stores with a search box and "Use my location", linking to /stores. Renders nothing without store pages. See Locations
pricingTable Badger Commerce's own plans and prices, with a monthly / yearly switch and Start free trial buttons. For Badger's marketing site; see Self-serve Sign-up
animationScene Animated scenes and scroll effects
faqExtension FAQ accordion
staticCarouselExtension Image/content carousel. urls makes each slide a link (a path on the shop or an http(s) address, blank for none); controls is both (arrows and dots, the default), dots (small, quiet dots only) or arrows. Phones show it square-cornered and full width. Each picture is cropped around its focal point; focalPoints (matched to images, "x y" or top/center/bottom) overrides it per slide.
scrollingImageCarousel Endless scrolling logo strip
youtubeVideo YouTube embed. Shows a poster image from the media library (or a plain panel) with a play button, and loads the video only when clicked, so YouTube sets no cookies before then
featuredProductExtension Featured products as a grid, carousel or cover flow
trendingProducts, recentlyViewedProducts Product lists from page views and the visitor's history
relatedProducts "You may also like" on product pages, read from the product's stored list of related products (generated in the background from shared collections and taxonomy category; no stock check). On the product stereotypes by default; see Extension System
collectionProductGrid A collection's product grid as a placeable block; see Extension System
contactUsExtension Contact form
emailCaptureExtension Email-capture tab that peeks up from the bottom of the page
socialLinks, likeExtension, discussionExtension Share buttons / account links, product likes, Disqus comments
openStreetMapExtension, chartStats Map and chart blocks
searchBar Storefront search box; see Search Bar

Site-wide extensions (Open Graph tags, theme CSS, favicon, analytics, Hotjar, Christmas mode, menu) are configured once per site. The full catalogue and how to write new ones is in Extension System.

Product references in text

A Markdown block can mention products without typing their names, prices or addresses, which go out of date the moment the shop changes them. References are written as ordinary Markdown and resolved each time the page is drawn, for the shopper looking at it:

Write Shows
[](product:AG-W-DRESS-WRAP) The product's current name, linked to its page
[the wrap dress](product:AG-W-DRESS-WRAP) Your words, linked to its page
{price:AG-W-DRESS-WRAP} Its current price in the shop's currency: "£65", "from £45" when its options are priced differently, "£55, was £69" on sale
{name:AG-W-DRESS-WRAP} Its current name, unlinked
[Knitwear](collection:knitwear), [Knitwear](category:/c/women/knitwear), [Size guide](page:size-guide) Links to a collection, a category page or a content page

A SKU can be a product's or one of its options' (a variant's link opens the product with that option chosen). A product the shopper can't see (disabled, deleted, or only in a staff-only collection) keeps the words without the link, and its price shows nothing, so a page never links to a missing product. All the products a block mentions are looked up together. Site search indexes the block's own words, not the codes. The wording of "from" and "was" is in the content.price.* messages.

In the admin, under a Markdown block's content, Insert a product searches the shop's products by name and adds [](product:SKU) ({price:SKU}) at the cursor (the visual editor shows the reference as a "product: SKU" chip), and Products in this text lists every product the text refers to with its name and price as they show now, flagging a code that matches no product. Agents using MCP are told to write references rather than names and prices.

Editing Markdown

A Markdown block's text is edited in a Markdown editor (themes/admin/js/markdown-editor.js) with two views, Visual (formatted, with a toolbar for bold, italic, headings, lists, quotes, links and code) and Markdown (the text itself). Either way the block saves Markdown, never HTML. Other rich-text blocks (htmlFragment) keep the HTML editor.

  • Opening a block changes nothing: its text is only rewritten once someone edits it in the visual view.
  • Text the visual view can't show without changing what it means (HTML, tables, footnotes and the like) opens as Markdown, and the visual view won't open on it. The test is a round trip: the text is put through the visual editor and back, and both must render the same.
  • Text saved as HTML by the old editor, which wrapped a block's Markdown in paragraphs so the shop showed it as plain text, opens with a Convert to Markdown button that turns it back.
  • The view last chosen is remembered in the browser.

The editor is ProseMirror with prosemirror-markdown and markdown-it, bundled by web-mvc/scripts/copy-versioned-deps.js (BUNDLES) into /vendor/prosemirror-markdown/<version>/badger-markdown-editor.min.js, which the editor loads only on a page with a Markdown block. The bundled packages are pinned together: the build fails if one of them isn't the version BUNDLES lists.

Media library

Admin → Media (/admin/media) stores images with title, alt text, description and keywords, searchable from every image picker. With AI image tagging on, uploads are keyworded and described automatically; see AI Integration and Enhanced Media Browser. Video is not stored: use a URL in a hero video background or a YouTube block.

Admin → Settings → Menu (/admin/shopSettings/menu) is a drag-and-drop tree editor.

  • Items link to a collection, page, product, external URL, or add a product to the basket; a collection item can expand its child collections automatically.
  • Items can be standard, mega-menu or content-panel nodes, and can be shown to signed-in customers only.
  • A site can have several menus. The menuGeneratorExtension places one in any slot; the main navigation uses default-menu-id (default mainMenu).
  • Footer link columns. Build a menu for the footer, then add a menuGeneratorExtension to the footer slot with its Menu ID Override set to that menu and Layout set to Footer columns. Each top-level item becomes a heading (a link if it has a URL) over its child links. This layout always sends the whole menu as plain links, with none of the navigation bar's browser caching or script.
  • An AI Menu Generator panel can draft the tree from a description; see AI Integration.
  • Mobile navigation (off-canvas menu or drawer) comes from the theme.

Blog

Admin → Blog (/admin/blog). A blog is a page; its posts are child pages with an author name and a date (editable, used for ordering). The blog has the blogPage stereotype and the fixed parent blogs (not a real page); the admin blog list and the RSS feed find blogs by that parent, so a blog made any other way needs it too (MCP and new sites set it; system update 109 repaired older ones). A post has the blogPost stereotype, the blog's seoName as its parent, and a seoName prefixed with the blog's (blog/my-post). Blocks:

  • blogListExtension: paginated list of posts, newest first. For a photo-led blog, turn on Display Images? and set its pageTemplateOverride to extensions/blogList/photoWall for a photo wall: each post's masthead photo at its own shape in a masonry of columns (the newest heading each column), with the date, title and description underneath. A photo opens full screen in a viewer (previous/next, arrow keys, swipe, Escape) with a "Read the story" link to the post; with the viewer unavailable it is a plain link to the post. When the posts on the page span more than one year, year chips filter the wall. The photo's alt text is the masthead image's, from the media library. On Diorama the photo wall is the default layout, with no pageTemplateOverride needed.
  • blogLatestPostsExtension: the latest few posts, for other pages. Cards by default; set its pageTemplateOverride to extensions/blogLatestPosts/incidentLog for a log (on a dark band, the newest post as a large card and the rest as rows of reference, title and date, for numbered posts such as callouts or matches: 2026-83: Thorpe Cloud – Unwell walker reads as reference 2026-83, title Thorpe Cloud, detail Unwell walker; split in Java by PostTitle) or to extensions/blogLatestPosts/timeline for a dated timeline (progress updates, an appeal). Both are Nova layouts, so every Nova-based theme has them; a theme can restyle them (Ridge does).
  • blogMastheadExtension: post title, image, author and date. A blog's own page (the blogPage stereotype) shows no date or author, since its date is only when the page was made. The masthead image is also used in listings and social tags.
  • blogRelatedArticlesExtension: other posts from the same blog, most recent or most viewed in the last 30 days.

A post lays out as a single reading column, or as the article beside a sidebar when its rightSection has anything in it. Put sidebar extensions (a call to action, related posts) on the blog's post stereotype to give every post the sidebar layout.

Posts have an RSS feed at /rss/{blogName}, newest first, dated by each post's published date. Comments are available through Disqus (discussionExtension). Pages can carry tags, used by Content Search filtering, but tags are not editable in admin yet.

Stereotypes

A stereotype (Admin → Site → Stereotypes, /admin/site/stereotypes) is a reusable set of extensions. Products, collections and pages that use one inherit its extensions. An item's own enabled extension with the same name in the same slot replaces the inherited one, and a stereotype can switch off or reconfigure site-wide extensions for the items that use it.

To drop an inherited extension from one item, delete it in that item's content block editor. The stereotype is left alone: the item gets an exclusion for that extension in that slot (ExtensionConfigurationBean.excludesInherited), and other items that use the stereotype keep the block. An exclusion never renders. The editor lists it, struck through, under its area as "Removed from here" with a Restore button, which removes the exclusion and brings the inherited block back (MCP: manageExtensionConfig restore). Hiding the item's own copy of a block doesn't do this: a disabled placement doesn't suppress the stereotype's. Editing an inherited block's settings, by contrast, changes the stereotype and so every item that uses it.

AI agents see each inherited block in extensionConfig as replaced or excluded, and exclude or restore one with manageExtensionConfig exclude / restore (extensionName, pageLocation).

A page's block changes can be made as a draft, previewed and then published, rather than going live as they are saved: see Block Drafts.

Content pages (/p/...) in Nova and the Brock family (Brock, Pop, Depot, Spec, Atelier) show a small breadcrumb trail just under the header, above any hero. It is built from the site's main menu (the menu named by default-menu-id), so it follows the navigation shoppers already use:

Page Trail
In a menu dropdown Home › Services › Legacy modernisation
A dropdown's own page, also listed as its first child ("All services" → services) Home › Services (the parent is not repeated)
Under a "Home" dropdown whose first child is the home page Home › Sponsors (the group is not repeated as a second Home)
A top-level menu item Home › About us
Not in the menu, with a parent page (a blog post) Home › Insights › Post title (the parent is placed via the menu when it is in it)
Neither Home › Page title
  • Labels are the menu text for menu items and the page's name for pages; every crumb but the current page is a link. A menu item with no link of its own links to its first child.
  • If a page is in the menu more than once, the shortest trail wins.
  • Hidden on the home page (seoName home, or whatever page landingPageRedirectURL points at) and on platform pages: basket, checkout, account, login, search, order confirmation and the 4xx/5xx error pages.
  • A matching schema.org BreadcrumbList JSON-LD block is emitted with absolute URLs (the site's domain over https), so search engines can show the trail in results.

Turn it off per site with Admin → Site Configuration, category breadcrumb-config, or the MCP manageSiteConfig tool:

Key Default Effect
cms-page-breadcrumbs-enabled true false hides the trail and its JSON-LD on every content page.

For developers. PageBreadcrumbService (commerce-core) resolves the trail from MenuService.extractMenu, the same cached menu tree the navigation renders, so there is no extra menu build per request; the only extra read is the parent page for pages outside the menu. PageController puts it on the model as pageBreadcrumbs and pageBreadcrumbsJsonLd. Each theme's fragment/nav.html includes fragment/breadcrumb :: pageBreadcrumb(<wrap class>) between the header and the bannerSection slot, so it sits above heroes in either bannerSection or topBanner. Atelier, whose header floats over a leading hero, floats the trail with it in white.

Collection and product pages show the trail their own controller builds (Home › Shop › Donations). It sits in the page's content, except when the page has a bannerSection block such as a hero: then it moves above the banner, under the header, as on content pages, rather than under the hero. This applies in every theme that shows breadcrumbs.

Not built

No drag-and-drop page builder or starter page templates, no scheduled publish/unpublish, no no revision history, no video hosting, no social feed embeds, no blog categories, no related products on posts, and no audience targeting, geo-targeting or A/B testing of content. HTML and Markdown blocks are rendered as entered, so only trusted admins should edit them.