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
displayPrioritysetting (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.
Menus¶
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
menuGeneratorExtensionplaces one in any slot; the main navigation usesdefault-menu-id(defaultmainMenu). - Footer link columns. Build a menu for the footer, then add a
menuGeneratorExtensionto thefooterslot 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 itspageTemplateOverridetoextensions/blogList/photoWallfor 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 nopageTemplateOverrideneeded.blogLatestPostsExtension: the latest few posts, for other pages. Cards by default; set itspageTemplateOverridetoextensions/blogLatestPosts/incidentLogfor 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 walkerreads as reference2026-83, titleThorpe Cloud, detailUnwell walker; split in Java byPostTitle) or toextensions/blogLatestPosts/timelinefor 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 (theblogPagestereotype) 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.
Breadcrumbs on content pages¶
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 pagelandingPageRedirectURLpoints at) and on platform pages: basket, checkout, account, login, search, order confirmation and the 4xx/5xx error pages. - A matching schema.org
BreadcrumbListJSON-LD block is emitted with absolute URLs (the site's domain overhttps), 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.